@downtrace/protocol 0.4.0 → 0.5.0

package/README.md

@@ -4,7 +4,7 @@ The ingestion contract between Downtrace agents and the Downtrace cloud, as a JS
 
 - `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()`, `CALLS_PER_REQUEST_BOUNDARIES_V0`, `CALLS_PER_REQUEST_BUCKETS_V0`, `callsPerRequestBucket()`, and the types `AggregatesBatch`, `Interval`, `Endpoint`, `LatencyHistogram`, `Dependency`, `PostgresStats`, …
+- Exports: `PROTOCOL_VERSION`, `ACCEPTED_PROTOCOL_VERSIONS_V0`, `AGGREGATES_PATH`, `AGGREGATES_SCHEMA_V0`, `LATENCY_BOUNDARIES_V0`, `LATENCY_BUCKETS_V0`, `latencyBucket()`, `CALLS_PER_REQUEST_BOUNDARIES_V0`, `CALLS_PER_REQUEST_BUCKETS_V0`, `callsPerRequestBucket()`, and the types `AggregatesBatch`, `Interval`, `Endpoint`, `LatencyHistogram`, `Dependency`, `PostgresStats`, …
 
 ## v0 in one sentence
 
@@ -16,7 +16,9 @@ Since **0.2.0** an endpoint may also carry `postgres`: how many queries each req
 
 ## How the protocol changes
 
-Fields are only ever **added**, and always optional. Each addition bumps the minor version, and the batch's `protocol` field is an enum of every published minor, so a cloud that speaks 0.2 still accepts an agent that speaks 0.1. Removing or renaming a field, or moving a histogram's bucket bounds, would be a major version on a new path. Bucket bounds are declared in the schema itself (`x-latency-boundaries-ms`, `x-queries-per-request-boundaries`), so they are part of the generated contract rather than a constant someone has to keep in sync.
+**The package version is the protocol version.** `@downtrace/protocol@0.5.0` speaks protocol `0.5.0`, and CI refuses to publish a release where the two disagree, so you can read the contract off the version in your lockfile. A release that changes the package without touching the contract moves the patch segment only.
+
+Fields are only ever **added**, and always optional. Each addition bumps the minor version, and the batch's `protocol` field is an enum of every published minor, so a cloud that speaks 0.2 still accepts an agent that speaks 0.1. Removing or renaming a field, or moving a histogram's bucket bounds, would be a major version on a new path. Bucket bounds are declared in the schema itself (`x-latency-boundaries-ms`, `x-calls-per-request-boundaries`), and so are the versions themselves, so they are part of the generated contract rather than a constant someone has to keep in sync.
 
 ## Source
 

package/dist/index.d.ts

@@ -215,12 +215,13 @@ declare const CALLS_PER_REQUEST_BOUNDARIES_V0: readonly number[];
 /** Number of calls-per-request buckets: boundaries + 1 open-ended bucket. */
 declare const CALLS_PER_REQUEST_BUCKETS_V0 = 8;
 //#endregion
-//#region src/index.d.ts
-/**
- * Version of the ingestion protocol this package speaks. Every published minor of v0 stays acceptable to the
- * cloud, so an agent on an older minor keeps working: fields are only ever added, and always optional (ADR 0008).
- */
+//#region src/generated/versions.d.ts
+/** Every published minor of v0, oldest first. The cloud never stops accepting one it published (ADR 0008). */
+declare const ACCEPTED_PROTOCOL_VERSIONS_V0: readonly ["0.1.0", "0.2.0", "0.3.0", "0.4.0", "0.5.0"];
+/** The newest published minor: what an up-to-date agent stamps on every batch. */
 declare const PROTOCOL_VERSION = "0.5.0";
+//#endregion
+//#region src/index.d.ts
 /** 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. */
@@ -595,4 +596,4 @@ declare function latencyBucket(ms: number): number;
 /** Index of the bucket a call count falls into: first boundary >= count, else the open-ended last bucket. */
 declare function callsPerRequestBucket(calls: number): number;
 //#endregion
-export { AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, type AgentInfo, type AggregatesBatch, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, type Dependency, type DeployInfo, type Endpoint, type InstanceInfo, type Interval, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, type LatencyHistogram, PROTOCOL_VERSION, type PostgresStats, type RuntimeHealth, type StatusClasses, callsPerRequestBucket, latencyBucket };
+export { ACCEPTED_PROTOCOL_VERSIONS_V0, AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, type AgentInfo, type AggregatesBatch, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, type Dependency, type DeployInfo, type Endpoint, type InstanceInfo, type Interval, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, type LatencyHistogram, PROTOCOL_VERSION, type PostgresStats, type RuntimeHealth, type StatusClasses, callsPerRequestBucket, latencyBucket };

package/dist/index.js

@@ -515,12 +515,19 @@ const CALLS_PER_REQUEST_BOUNDARIES_V0 = [
 /** Number of calls-per-request buckets: boundaries + 1 open-ended bucket. */
 const CALLS_PER_REQUEST_BUCKETS_V0 = 8;
 //#endregion
-//#region src/index.ts
-/**
-* Version of the ingestion protocol this package speaks. Every published minor of v0 stays acceptable to the
-* cloud, so an agent on an older minor keeps working: fields are only ever added, and always optional (ADR 0008).
-*/
+//#region src/generated/versions.ts
+/** Every published minor of v0, oldest first. The cloud never stops accepting one it published (ADR 0008). */
+const ACCEPTED_PROTOCOL_VERSIONS_V0 = [
+	"0.1.0",
+	"0.2.0",
+	"0.3.0",
+	"0.4.0",
+	"0.5.0"
+];
+/** The newest published minor: what an up-to-date agent stamps on every batch. */
 const PROTOCOL_VERSION = "0.5.0";
+//#endregion
+//#region src/index.ts
 /** 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. */
@@ -544,4 +551,4 @@ function callsPerRequestBucket(calls) {
 	return n;
 }
 //#endregion
-export { AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, callsPerRequestBucket, latencyBucket };
+export { ACCEPTED_PROTOCOL_VERSIONS_V0, AGGREGATES_PATH, AGGREGATES_SCHEMA_V0, CALLS_PER_REQUEST_BOUNDARIES_V0, CALLS_PER_REQUEST_BUCKETS_V0, LATENCY_BOUNDARIES_V0, LATENCY_BUCKETS_V0, PROTOCOL_VERSION, callsPerRequestBucket, latencyBucket };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@downtrace/protocol",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Downtrace ingestion protocol: JSON Schema, fixtures and generated TypeScript types",
   "type": "module",
   "exports": {