@downtrace/protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Raúl Jiménez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# @downtrace/protocol
+
+The ingestion contract between Downtrace agents and the Downtrace cloud, as a JSON Schema (draft 2020-12) plus the TypeScript types generated from it.
+
+- `schema/v0/aggregates.schema.json` — the contract. Everything else derives from it.
+- `schema/v0/fixtures/{valid,invalid}/` — examples every implementation must accept and reject.
+- Exports: `PROTOCOL_VERSION`, `AGGREGATES_PATH`, `AGGREGATES_SCHEMA_V0`, `LATENCY_BOUNDARIES_V0`, `LATENCY_BUCKETS_V0`, `latencyBucket()`, and the types `AggregatesBatch`, `Interval`, `Endpoint`, `LatencyHistogram`, …
+
+## v0 in one sentence
+
+Every 10 seconds, for every route, an agent sends how many requests there were, how many failed, how statuses split, and a **35-bucket fixed latency histogram** (0.5 ms → 60 s). Fixed buckets add up across instances, so the cloud can compute fleet-wide percentiles.
+
+`POST {DOWNTRACE_URL}/v0/aggregates` · `Authorization: Bearer <token>` · JSON · 202 accepted, 400 invalid, 401 bad token.
+
+## Source
+
+Developed in a monorepo and mirrored read-only to [RadW2020/downtrace-agent](https://github.com/RadW2020/downtrace-agent). MIT.

package/dist/index.d.ts

@@ -0,0 +1,334 @@
+//#region src/generated/aggregates.d.ts
+/**
+ * A batch of per-interval, per-route aggregates sent by an agent to the cloud (POST /v0/aggregates).
+ */
+interface AggregatesBatch {
+  /**
+   * Protocol version this batch conforms to.
+   */
+  protocol: "0.1.0";
+  agent: AgentInfo;
+  instance: InstanceInfo;
+  deploy: DeployInfo;
+  /**
+   * @minItems 1
+   * @maxItems 6
+   */
+  intervals: [Interval] | [Interval, Interval] | [Interval, Interval, Interval] | [Interval, Interval, Interval, Interval] | [Interval, Interval, Interval, Interval, Interval] | [Interval, Interval, Interval, Interval, Interval, Interval];
+}
+interface AgentInfo {
+  name: string;
+  version: string;
+  runtime: "node" | "go";
+  runtimeVersion: string;
+}
+interface InstanceInfo {
+  /**
+   * Random identifier generated once per process.
+   */
+  id: string;
+  hostname: string;
+  pid: number;
+}
+interface DeployInfo {
+  /**
+   * Deployed version or commit; "unknown" when undetectable.
+   */
+  version: string;
+  environment: string;
+}
+interface Interval {
+  /**
+   * Interval start, Unix epoch milliseconds.
+   */
+  start: number;
+  durationMs: number;
+  /**
+   * @maxItems 4096
+   */
+  endpoints: Endpoint[];
+}
+interface Endpoint {
+  method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS" | "OTHER";
+  /**
+   * Normalised route template, e.g. /products/:id, or (other).
+   */
+  route: string;
+  count: number;
+  /**
+   * Responses with a 5xx status.
+   */
+  errors: number;
+  status: StatusClasses;
+  latency: LatencyHistogram;
+}
+interface StatusClasses {
+  /**
+   * 2xx
+   */
+  success: number;
+  /**
+   * 3xx
+   */
+  redirect: number;
+  /**
+   * 4xx
+   */
+  clientError: number;
+  /**
+   * 5xx
+   */
+  serverError: number;
+}
+/**
+ * Fixed-bucket latency histogram in milliseconds. counts[i] is the number of requests with latency <= boundaries[i]; the last bucket holds everything above the last boundary. Fixed buckets add up across instances.
+ */
+interface LatencyHistogram {
+  /**
+   * @minItems 35
+   * @maxItems 35
+   */
+  counts: [number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number, number];
+  /**
+   * Sum of latencies in ms.
+   */
+  sum: number;
+  /**
+   * Maximum latency in ms.
+   */
+  max: number;
+}
+//#endregion
+//#region src/generated/boundaries.d.ts
+/** Upper bounds (ms) of the fixed latency buckets; the last bucket is open-ended. */
+declare const LATENCY_BOUNDARIES_V0: readonly number[];
+/** Number of buckets: boundaries + 1 open-ended bucket. */
+declare const LATENCY_BUCKETS_V0 = 35;
+//#endregion
+//#region src/index.d.ts
+/** Version of the ingestion protocol spoken by agents and the cloud. */
+declare const PROTOCOL_VERSION = "0.1.0";
+/** Path, relative to the ingest URL, that receives AggregatesBatch payloads. */
+declare const AGGREGATES_PATH = "/v0/aggregates";
+/** The JSON Schema (draft 2020-12) for AggregatesBatch, for validators on either side. */
+declare const AGGREGATES_SCHEMA_V0: {
+  $schema: string;
+  $id: string;
+  title: string;
+  description: string;
+  type: string;
+  additionalProperties: boolean;
+  required: string[];
+  properties: {
+    protocol: {
+      type: string;
+      const: string;
+      description: string;
+    };
+    agent: {
+      $ref: string;
+    };
+    instance: {
+      $ref: string;
+    };
+    deploy: {
+      $ref: string;
+    };
+    intervals: {
+      type: string;
+      minItems: number;
+      maxItems: number;
+      items: {
+        $ref: string;
+      };
+    };
+  };
+  $defs: {
+    AgentInfo: {
+      title: string;
+      type: string;
+      additionalProperties: boolean;
+      required: string[];
+      properties: {
+        name: {
+          type: string;
+          minLength: number;
+          maxLength: number;
+        };
+        version: {
+          type: string;
+          minLength: number;
+          maxLength: number;
+        };
+        runtime: {
+          enum: string[];
+        };
+        runtimeVersion: {
+          type: string;
+          minLength: number;
+          maxLength: number;
+        };
+      };
+    };
+    InstanceInfo: {
+      title: string;
+      type: string;
+      additionalProperties: boolean;
+      required: string[];
+      properties: {
+        id: {
+          type: string;
+          minLength: number;
+          maxLength: number;
+          description: string;
+        };
+        hostname: {
+          type: string;
+          minLength: number;
+          maxLength: number;
+        };
+        pid: {
+          type: string;
+          minimum: number;
+        };
+      };
+    };
+    DeployInfo: {
+      title: string;
+      type: string;
+      additionalProperties: boolean;
+      required: string[];
+      properties: {
+        version: {
+          type: string;
+          minLength: number;
+          maxLength: number;
+          description: string;
+        };
+        environment: {
+          type: string;
+          minLength: number;
+          maxLength: number;
+        };
+      };
+    };
+    Interval: {
+      title: string;
+      type: string;
+      additionalProperties: boolean;
+      required: string[];
+      properties: {
+        start: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        durationMs: {
+          type: string;
+          minimum: number;
+          maximum: number;
+        };
+        endpoints: {
+          type: string;
+          maxItems: number;
+          items: {
+            $ref: string;
+          };
+        };
+      };
+    };
+    Endpoint: {
+      title: string;
+      type: string;
+      additionalProperties: boolean;
+      required: string[];
+      properties: {
+        method: {
+          enum: string[];
+        };
+        route: {
+          type: string;
+          minLength: number;
+          maxLength: number;
+          description: string;
+        };
+        count: {
+          type: string;
+          minimum: number;
+        };
+        errors: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        status: {
+          $ref: string;
+        };
+        latency: {
+          $ref: string;
+        };
+      };
+    };
+    StatusClasses: {
+      title: string;
+      type: string;
+      additionalProperties: boolean;
+      required: string[];
+      properties: {
+        success: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        redirect: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        clientError: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        serverError: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+      };
+    };
+    LatencyHistogram: {
+      title: string;
+      description: string;
+      type: string;
+      additionalProperties: boolean;
+      required: string[];
+      "x-latency-boundaries-ms": number[];
+      properties: {
+        counts: {
+          type: string;
+          minItems: number;
+          maxItems: number;
+          items: {
+            type: string;
+            minimum: number;
+          };
+        };
+        sum: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+        max: {
+          type: string;
+          minimum: number;
+          description: string;
+        };
+      };
+    };
+  };
+};
+/** Index of the bucket a latency (ms) falls into: first boundary >= latency, else the open-ended last bucket. */
+declare function latencyBucket(ms: number): number;
+//#endregion
+export { AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, type AgentInfo, type AggregatesBatch, type DeployInfo, type Endpoint, type InstanceInfo, type Interval, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, type LatencyHistogram, PROTOCOL_VERSION, type StatusClasses, latencyBucket };

package/dist/index.js

@@ -0,0 +1,339 @@
+//#region schema/v0/aggregates.schema.json
+var aggregates_schema_default = {
+	$schema: "https://json-schema.org/draft/2020-12/schema",
+	$id: "https://downtrace.io/schema/v0/aggregates.schema.json",
+	title: "AggregatesBatch",
+	description: "A batch of per-interval, per-route aggregates sent by an agent to the cloud (POST /v0/aggregates).",
+	type: "object",
+	additionalProperties: false,
+	required: [
+		"protocol",
+		"agent",
+		"instance",
+		"deploy",
+		"intervals"
+	],
+	properties: {
+		"protocol": {
+			"type": "string",
+			"const": "0.1.0",
+			"description": "Protocol version this batch conforms to."
+		},
+		"agent": { "$ref": "#/$defs/AgentInfo" },
+		"instance": { "$ref": "#/$defs/InstanceInfo" },
+		"deploy": { "$ref": "#/$defs/DeployInfo" },
+		"intervals": {
+			"type": "array",
+			"minItems": 1,
+			"maxItems": 6,
+			"items": { "$ref": "#/$defs/Interval" }
+		}
+	},
+	$defs: {
+		"AgentInfo": {
+			"title": "AgentInfo",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"name",
+				"version",
+				"runtime",
+				"runtimeVersion"
+			],
+			"properties": {
+				"name": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 128
+				},
+				"version": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 64
+				},
+				"runtime": { "enum": ["node", "go"] },
+				"runtimeVersion": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 64
+				}
+			}
+		},
+		"InstanceInfo": {
+			"title": "InstanceInfo",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"id",
+				"hostname",
+				"pid"
+			],
+			"properties": {
+				"id": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 64,
+					"description": "Random identifier generated once per process."
+				},
+				"hostname": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 253
+				},
+				"pid": {
+					"type": "integer",
+					"minimum": 0
+				}
+			}
+		},
+		"DeployInfo": {
+			"title": "DeployInfo",
+			"type": "object",
+			"additionalProperties": false,
+			"required": ["version", "environment"],
+			"properties": {
+				"version": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 128,
+					"description": "Deployed version or commit; \"unknown\" when undetectable."
+				},
+				"environment": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 64
+				}
+			}
+		},
+		"Interval": {
+			"title": "Interval",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"start",
+				"durationMs",
+				"endpoints"
+			],
+			"properties": {
+				"start": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Interval start, Unix epoch milliseconds."
+				},
+				"durationMs": {
+					"type": "integer",
+					"minimum": 1,
+					"maximum": 36e5
+				},
+				"endpoints": {
+					"type": "array",
+					"maxItems": 4096,
+					"items": { "$ref": "#/$defs/Endpoint" }
+				}
+			}
+		},
+		"Endpoint": {
+			"title": "Endpoint",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"method",
+				"route",
+				"count",
+				"errors",
+				"status",
+				"latency"
+			],
+			"properties": {
+				"method": { "enum": [
+					"GET",
+					"POST",
+					"PUT",
+					"PATCH",
+					"DELETE",
+					"HEAD",
+					"OPTIONS",
+					"OTHER"
+				] },
+				"route": {
+					"type": "string",
+					"minLength": 1,
+					"maxLength": 256,
+					"description": "Normalised route template, e.g. /products/:id, or (other)."
+				},
+				"count": {
+					"type": "integer",
+					"minimum": 0
+				},
+				"errors": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "Responses with a 5xx status."
+				},
+				"status": { "$ref": "#/$defs/StatusClasses" },
+				"latency": { "$ref": "#/$defs/LatencyHistogram" }
+			}
+		},
+		"StatusClasses": {
+			"title": "StatusClasses",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"success",
+				"redirect",
+				"clientError",
+				"serverError"
+			],
+			"properties": {
+				"success": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "2xx"
+				},
+				"redirect": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "3xx"
+				},
+				"clientError": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "4xx"
+				},
+				"serverError": {
+					"type": "integer",
+					"minimum": 0,
+					"description": "5xx"
+				}
+			}
+		},
+		"LatencyHistogram": {
+			"title": "LatencyHistogram",
+			"description": "Fixed-bucket latency histogram in milliseconds. counts[i] is the number of requests with latency <= boundaries[i]; the last bucket holds everything above the last boundary. Fixed buckets add up across instances.",
+			"type": "object",
+			"additionalProperties": false,
+			"required": [
+				"counts",
+				"sum",
+				"max"
+			],
+			"x-latency-boundaries-ms": [
+				.5,
+				1,
+				1.5,
+				2,
+				3,
+				4,
+				5,
+				7.5,
+				10,
+				15,
+				20,
+				30,
+				40,
+				50,
+				75,
+				100,
+				150,
+				200,
+				300,
+				400,
+				500,
+				750,
+				1e3,
+				1500,
+				2e3,
+				3e3,
+				4e3,
+				5e3,
+				7500,
+				1e4,
+				15e3,
+				2e4,
+				3e4,
+				6e4
+			],
+			"properties": {
+				"counts": {
+					"type": "array",
+					"minItems": 35,
+					"maxItems": 35,
+					"items": {
+						"type": "integer",
+						"minimum": 0
+					}
+				},
+				"sum": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Sum of latencies in ms."
+				},
+				"max": {
+					"type": "number",
+					"minimum": 0,
+					"description": "Maximum latency in ms."
+				}
+			}
+		}
+	}
+};
+//#endregion
+//#region src/generated/boundaries.ts
+/** Upper bounds (ms) of the fixed latency buckets; the last bucket is open-ended. */
+const LATENCY_BOUNDARIES_V0 = [
+	.5,
+	1,
+	1.5,
+	2,
+	3,
+	4,
+	5,
+	7.5,
+	10,
+	15,
+	20,
+	30,
+	40,
+	50,
+	75,
+	100,
+	150,
+	200,
+	300,
+	400,
+	500,
+	750,
+	1e3,
+	1500,
+	2e3,
+	3e3,
+	4e3,
+	5e3,
+	7500,
+	1e4,
+	15e3,
+	2e4,
+	3e4,
+	6e4
+];
+/** Number of buckets: boundaries + 1 open-ended bucket. */
+const LATENCY_BUCKETS_V0 = 35;
+//#endregion
+//#region src/index.ts
+/** Version of the ingestion protocol spoken by agents and the cloud. */
+const PROTOCOL_VERSION = "0.1.0";
+/** Path, relative to the ingest URL, that receives AggregatesBatch payloads. */
+const AGGREGATES_PATH = "/v0/aggregates";
+/** The JSON Schema (draft 2020-12) for AggregatesBatch, for validators on either side. */
+const AGGREGATES_SCHEMA_V0 = aggregates_schema_default;
+/** Index of the bucket a latency (ms) falls into: first boundary >= latency, else the open-ended last bucket. */
+function latencyBucket(ms) {
+	const n = LATENCY_BOUNDARIES_V0.length;
+	for (let i = 0; i < n; i++) {
+		const bound = LATENCY_BOUNDARIES_V0[i];
+		if (bound !== void 0 && ms <= bound) return i;
+	}
+	return n;
+}
+//#endregion
+export { AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, latencyBucket };