@oisasoje/gloo-receiver 📊

A lightweight, high-performance telemetry receiver and WebSocket broadcaster server for Gloo request tracing.

It listens on port 7777 by default, hosting the visualizer dashboard UI and accepting request trace payloads from the @oisasoje/gloo SDK to stream them in real time.

Features

• ⚡ High-Performance Collector: Ingestion engine running on port 7777.
• 🌳 Capped Memory DB: Implements a strict O(1) capped eviction Map (limits traces to a maximum of 500 to prevent memory leaks in dev).
• 📊 Live Broadcasts: Instantly broadcasts completed trace nodes and deletion triggers to connected dashboards via WebSockets.
• 🛑 Process Safety: Zero disk writes or database configuration overhead, keeping execution 100% in-memory and ephemeral.

Internal Component

This package is the internal telemetry engine for the Gloo system. You do not need to install or run it directly.

Instead, use the Gloo CLI to start the entire visualizer suite:

npm install -g @oisasoje/gloo-cli
gloo dev

When started via the CLI, the receiver:

1. Ingests traces on http://localhost:7777/trace.
2. Hosts the visualizer dashboard UI directly on http://localhost:7777.

REST API Specification

The receiver exposes a simplified REST API for trace ingestion and management:

| Method | Endpoint | Description | | :--- | :--- | :--- | | POST | /trace | Ingestion endpoint (used internally by the SDK to post completed traces). | | GET | /traces | Fetches all active traces stored in memory. | | GET | /traces/:id | Fetches details for a single trace by UUID. | | DELETE | /traces | Clears all stored traces in-memory and syncs visualizers. | | DELETE | /traces/:id | Deletes a single trace by UUID and syncs visualizers. |

[!NOTE] All other frontend assets (such as HTML, JS, CSS) are served by the receiver from its internal static out/ directory, with SPA fallback routing.

WebSocket Stream Protocol

Clients connect to ws://localhost:7777 to stream updates in real time.

Broadcast JSON Envelope

All messages sent over the WebSocket follow this envelope structure:

{
  "type": "trace" | "clear" | "clearById",
  "payload": any
}

• trace Event: Emitted when a new request completes. Payload contains { id, body: { ...traceDetails } }.
• clear Event: Emitted when all traces are cleared from memory. Payload is [].
• clearById Event: Emitted when a single trace is deleted. Payload is { id: "clearById", body: "trace-uuid" }.

Architecture (v1)

[ Express App (Gloo SDK) ] ──(HTTP POST)──> localhost:7777 (gloo-receiver)
                                                      │
                                           (Serves static UI files)
                                                      ▼
                                           localhost:7777 (gloo-ui in browser)
                                                      │
                                             (WebSocket Stream)
                                                      ▼
                                            ws://localhost:7777

Notes

• Designed purely for local developer observability.
• Uses an ephemeral, in-memory Map capped at 500 traces to preserve machine performance.
• The receiver must be running before starting your Express app so that the SDK telemetry POST calls do not fail.