@ancplua/qyl-api-schema 11.5.0 → 11.6.0

package/README.md

@@ -4,12 +4,42 @@ The TypeSpec source of truth for Qyl's client-visible product API. This reposito
 emits the public schema and contract artifacts; it does not implement the server,
 storage engine, or OTLP receiver.
 
-Qyl stores and exposes traces, logs, and metrics. The metric surface is read-only.
-`GET /api/v1/metrics` lists the metric descriptors recorded for a project,
-`GET /api/v1/metrics/{metric_name}/series` lists the distinct attribute streams
-under one metric name, and `GET /api/v1/metrics/{metric_name}/query` aggregates one
-metric over a time range into buckets. Metric points are written over OTLP, which
-this contract does not describe. Profiles are not supported.
+The contract covers every client-visible surface of a qyl collector and runner:
+
+- **Traces** — `GET /api/v1/traces`, one trace, and its spans (`api/routes.tsp`,
+  `otel/span.tsp`).
+- **Logs** — `GET /api/v1/logs` and the live SSE stream `GET /api/v1/stream/logs`
+  with its heartbeat (`api/streaming.tsp`, `otel/logs.tsp`).
+- **Metrics**, read-only — `GET /api/v1/metrics` lists the metric descriptors
+  recorded for a project, `GET /api/v1/metrics/{metric_name}/series` lists the
+  distinct attribute streams under one metric name, and
+  `GET /api/v1/metrics/{metric_name}/query` aggregates one metric over a time range
+  into buckets (`models/metrics.tsp`). Metric points are written over OTLP, which
+  this contract does not describe. Profiles are not supported.
+- **Sessions** — `GET /api/v1/sessions`, one session, its traces and `/stats`
+  (`models/session.tsp`).
+- **Health** — `GET /health` and `GET /alive`, whose `HealthReport` carries the
+  `contract_revision` handshake (`models/health.tsp`).
+- **MCP tools** — the input and structured-output models of the qyl MCP tools
+  (`models/mcp-tools.tsp`).
+- **Workbench** — the local MCP workbench: sessions, workspaces, servers, protocol
+  streams, executions, test cases, suites, evaluation runs and exports
+  (`api/workbench.tsp`, `models/workbench.tsp`).
+- **Runner** — the local runner's loopback-only `/runner/resources` snapshot, SSE
+  streams, logs and restart/stop actions (`api/runner.tsp`, `models/runner.tsp`).
+- **Shared** — `ProblemDetails` errors, cursor pagination and the common scalars
+  (`common/`), plus the OTel resource, span and log projections (`otel/`).
+
+Telemetry itself is never changed or deleted through this contract; retention
+removes it. The only writable resources are the ones a user creates:
+annotations (`/api/v1/annotations`, a note of at most 2000 characters on a trace,
+span or session) and saved queries (`/api/v1/saved-queries`, a named structured
+filter for traces, logs or metrics, run with `POST …/{saved_query_id}:run`). Both
+extend the shared write base in `common/resource.tsp`: server-assigned `id`,
+`created_at`, `updated_at` and `etag`; `Idempotency-Key` on create, which answers
+`201` with `Location`; `If-Match` on `PATCH` and `DELETE`, refused with `428` when
+missing and `412` when stale. Collector keys carry the roles `ingest`, `read`,
+`write` and `delete` (`CollectorKeyRole`); writes need `write`, deletes `delete`.
 
 ## Contract pipeline
 
@@ -56,6 +86,18 @@ rather than from prose here; this line moves faster than a README is revised.
 `main.tsp` is the local compile entry point and includes emitter routing. `index.tsp`
 is the published TypeSpec entry point and contains only the client-facing contract.
 
+### Package exports
+
+| Subpath | Content |
+| --- | --- |
+| `@ancplua/qyl-api-schema` | `index.tsp`, the whole TypeSpec contract |
+| `@ancplua/qyl-api-schema/otel` | `otel/otel-conventions.tsp`: only the OTel-shaped resource, span and log models, for TypeSpec consumers that do not want the qyl API |
+| `@ancplua/qyl-api-schema/types` | Generated TypeScript contract types and the `CONTRACT_REVISION` constant |
+| `@ancplua/qyl-api-schema/openapi` | `qyl.openapi.json` |
+| `@ancplua/qyl-api-schema/json-schema` | The bundled JSON Schema |
+| `@ancplua/qyl-api-schema/zod` | Runtime validators, below |
+| `@ancplua/qyl-api-schema/runtime` | Presentation helpers over the generated `AttributeValue` matcher (`decodeAttributeValue`, `formatAttributeValue`, `attributeString`, `attributeNumber`, `attributeIdentity`, `matchAttributeValue`) and the `UnixNanos` string helpers (`parseUnixNanos`, `compareUnixNanos`, `unixNanosDelta`, `unixNanosToEpochMs`, `unixNanosToIso`, `epochMsToUnixNanos`). Authored in `src/runtime/`, compiled to `generated/runtime/` |
+
 ## Runtime validation
 
 `@ancplua/qyl-api-schema/zod` builds Zod validators from the bundled JSON Schema at

package/api/routes.tsp

@@ -9,6 +9,10 @@ import "../otel/logs.tsp";
 import "../models/session.tsp";
 import "../models/health.tsp";
 import "../models/metrics.tsp";
+import "../common/resource.tsp";
+import "../common/auth.tsp";
+import "../models/annotations.tsp";
+import "../models/saved-queries.tsp";
 
 using TypeSpec.Http;
 using TypeSpec.OpenAPI;
@@ -22,10 +26,13 @@ using Qyl.Api.Contracts.OTel.Metrics;
 using Qyl.Api.Contracts.OTel.Enums;
 using Qyl.Api.Contracts.Domains.Observe.Session;
 using Qyl.Api.Contracts.Health;
+using Qyl.Api.Contracts.Annotations;
+using Qyl.Api.Contracts.SavedQueries;
 
 @service(#{ title: "qyl API" })
 namespace Qyl.Api.Contracts;
 
+// The query routes require a key with the `read` role (CollectorKeyRole.read).
 alias QylApiKeyHeaderAuth = ApiKeyAuth<ApiKeyLocation.header, "x-otlp-api-key">;
 
 @doc("Optional project scope applied to collector query operations.")
@@ -46,12 +53,28 @@ interface TracesApi {
   list(
     ...ProjectScopeHeader,
 
+    @doc("Keep traces that started at or after this time.")
+    @query("start_time")
+    startTime?: utcDateTime,
+
+    @doc("Keep traces that started before this time.")
+    @query("end_time")
+    endTime?: utcDateTime,
+
+    @doc("Keep traces with at least one span from this service.")
+    @query("service_name")
+    serviceName?: string,
+
+    @doc("Keep only traces with at least one error span.")
+    @query("errors_only")
+    errorsOnly?: boolean,
+
     @query
     @minValue(1)
     @maxValue(1000)
     limit?: int32 = 100,
 
-    @query cursor?: string,
+    @query cursor?: Cursor,
   ):
     | CursorPage<Trace>
     | ValidationError
@@ -68,8 +91,20 @@ interface TracesApi {
 
   @get
   @route("/{trace_id}/spans")
-  getSpans(...ProjectScopeHeader, @path("trace_id") traceId: TraceId):
+  getSpans(
+    ...ProjectScopeHeader,
+    @path("trace_id") traceId: TraceId,
+
+    @doc("Page size. Omitted, every span of the trace is returned in one page.")
+    @query
+    @minValue(1)
+    @maxValue(10000)
+    limit?: int32,
+
+    @query cursor?: Cursor,
+  ):
     | CursorPage<Span>
+    | ValidationError
     | NotFoundError
     | UnauthorizedError
     | InternalServerError;
@@ -99,6 +134,8 @@ interface LogsApi {
     @minValue(1)
     @maxValue(10000)
     limit?: int32 = 100,
+
+    @query cursor?: Cursor,
   ):
     | CursorPage<LogRecord>
     | ValidationError
@@ -132,6 +169,8 @@ interface MetricsApi {
     @minValue(1)
     @maxValue(1000)
     limit?: int32 = 200,
+
+    @query cursor?: Cursor,
   ):
     | CursorPage<MetricDescriptor>
     | ValidationError
@@ -160,6 +199,8 @@ interface MetricsApi {
     @minValue(1)
     @maxValue(1000)
     limit?: int32 = 200,
+
+    @query cursor?: Cursor,
   ):
     | CursorPage<MetricSeries>
     | ValidationError
@@ -176,7 +217,6 @@ interface MetricsApi {
   query(
     ...ProjectScopeHeader,
     @path("metric_name") metricName: string,
-
     @query("start_time") startTime: utcDateTime,
     @query("end_time") endTime: utcDateTime,
 
@@ -233,7 +273,7 @@ interface SessionsApi {
     @maxValue(1000)
     limit?: int32 = 100,
 
-    @query cursor?: string,
+    @query cursor?: Cursor,
   ):
     | CursorPage<SessionEntity>
     | ValidationError
@@ -250,8 +290,20 @@ interface SessionsApi {
 
   @get
   @route("/{session_id}/traces")
-  getTraces(...ProjectScopeHeader, @path("session_id") sessionId: SessionId):
+  getTraces(
+    ...ProjectScopeHeader,
+    @path("session_id") sessionId: SessionId,
+
+    @doc("Page size; the response is bounded even when omitted.")
+    @query
+    @minValue(1)
+    @maxValue(1000)
+    limit?: int32 = 100,
+
+    @query cursor?: Cursor,
+  ):
     | CursorPage<Trace>
+    | ValidationError
     | NotFoundError
     | UnauthorizedError
     | InternalServerError;
@@ -265,6 +317,242 @@ interface SessionsApi {
   ): SessionStats | ValidationError | UnauthorizedError | InternalServerError;
 }
 
+// -----------------------------------------------------------------------------
+// Annotations
+//
+// User notes on a trace, span or session (models/annotations.tsp). Reads take
+// a `read` key, create and update a `write` key, delete a `delete` key.
+// -----------------------------------------------------------------------------
+
+@route("/api/v1/annotations")
+@tag("Annotations")
+interface AnnotationsApi {
+  @doc("Attach a note of at most 2000 characters to a trace, span or session.")
+  @useAuth(QylWriteKeyAuth)
+  @post
+  create(
+    ...ProjectScopeHeader,
+    ...IdempotencyKeyHeader,
+    @body request: AnnotationCreateRequest,
+  ):
+    | {
+        @statusCode statusCode: 201;
+
+        @doc("URL of the created annotation.")
+        @header("Location")
+        location: string;
+
+        @header("ETag") etag: ETag;
+        @body body: Annotation;
+      }
+    | ValidationError
+    | UnauthorizedError
+    | ForbiddenError
+    | NotFoundError
+    | ConflictError
+    | InternalServerError;
+
+  @doc("List annotations, newest first, optionally only those attached to one trace, span or session.")
+  @useAuth(QylApiKeyHeaderAuth)
+  @get
+  list(
+    ...ProjectScopeHeader,
+
+    @doc("Annotations on this trace, including those on its spans.")
+    @query("trace_id")
+    traceId?: TraceId,
+
+    @doc("Annotations on this span; requires `trace_id`.")
+    @query("span_id")
+    spanId?: SpanId,
+
+    @query("session_id") sessionId?: SessionId,
+
+    @query
+    @minValue(1)
+    @maxValue(1000)
+    limit?: int32 = 100,
+
+    @query cursor?: Cursor,
+  ):
+    | CursorPage<Annotation>
+    | ValidationError
+    | UnauthorizedError
+    | InternalServerError;
+
+  @useAuth(QylApiKeyHeaderAuth)
+  @get
+  @route("/{annotation_id}")
+  get(...ProjectScopeHeader, @path("annotation_id") annotationId: ResourceId):
+    | {
+        @header("ETag") etag: ETag;
+        @body body: Annotation;
+      }
+    | NotFoundError
+    | UnauthorizedError
+    | InternalServerError;
+
+  @doc("Replace the text of an annotation. The target is fixed at creation.")
+  @useAuth(QylWriteKeyAuth)
+  @patch(#{ implicitOptionality: false })
+  @route("/{annotation_id}")
+  update(
+    ...ProjectScopeHeader,
+    ...IfMatchHeader,
+    @path("annotation_id") annotationId: ResourceId,
+    @body request: AnnotationUpdateRequest,
+  ):
+    | {
+        @header("ETag") etag: ETag;
+        @body body: Annotation;
+      }
+    | ValidationError
+    | UnauthorizedError
+    | ForbiddenError
+    | NotFoundError
+    | PreconditionFailedError
+    | PreconditionRequiredError
+    | InternalServerError;
+
+  @doc("Delete one annotation. Telemetry is never deleted.")
+  @useAuth(QylDeleteKeyAuth)
+  @delete
+  @route("/{annotation_id}")
+  delete(
+    ...ProjectScopeHeader,
+    ...IfMatchHeader,
+    @path("annotation_id") annotationId: ResourceId,
+  ):
+    | NoContentResponse
+    | UnauthorizedError
+    | ForbiddenError
+    | NotFoundError
+    | PreconditionFailedError
+    | PreconditionRequiredError
+    | InternalServerError;
+}
+
+// -----------------------------------------------------------------------------
+// Saved queries
+//
+// Named, structured filters for traces, logs or metrics
+// (models/saved-queries.tsp). Names are unique per project.
+// -----------------------------------------------------------------------------
+
+@route("/api/v1/saved-queries")
+@tag("Saved queries")
+interface SavedQueriesApi {
+  @doc("Save a named filter. A name already used in the project is refused with 409.")
+  @useAuth(QylWriteKeyAuth)
+  @post
+  create(
+    ...ProjectScopeHeader,
+    ...IdempotencyKeyHeader,
+    @body request: SavedQueryCreateRequest,
+  ):
+    | {
+        @statusCode statusCode: 201;
+
+        @doc("URL of the created saved query.")
+        @header("Location")
+        location: string;
+
+        @header("ETag") etag: ETag;
+        @body body: SavedQuery;
+      }
+    | ValidationError
+    | UnauthorizedError
+    | ForbiddenError
+    | ConflictError
+    | InternalServerError;
+
+  @doc("List the project's saved queries by name.")
+  @useAuth(QylApiKeyHeaderAuth)
+  @get
+  list(
+    ...ProjectScopeHeader,
+    @query signal?: SavedQuerySignal,
+
+    @query
+    @minValue(1)
+    @maxValue(1000)
+    limit?: int32 = 100,
+
+    @query cursor?: Cursor,
+  ):
+    | CursorPage<SavedQuery>
+    | ValidationError
+    | UnauthorizedError
+    | InternalServerError;
+
+  @useAuth(QylApiKeyHeaderAuth)
+  @get
+  @route("/{saved_query_id}")
+  get(...ProjectScopeHeader, @path("saved_query_id") savedQueryId: ResourceId):
+    | {
+        @header("ETag") etag: ETag;
+        @body body: SavedQuery;
+      }
+    | NotFoundError
+    | UnauthorizedError
+    | InternalServerError;
+
+  @doc("Change a saved query. Renaming onto a name already used in the project is refused with 409.")
+  @useAuth(QylWriteKeyAuth)
+  @patch(#{ implicitOptionality: false })
+  @route("/{saved_query_id}")
+  update(
+    ...ProjectScopeHeader,
+    ...IfMatchHeader,
+    @path("saved_query_id") savedQueryId: ResourceId,
+    @body request: SavedQueryUpdateRequest,
+  ):
+    | {
+        @header("ETag") etag: ETag;
+        @body body: SavedQuery;
+      }
+    | ValidationError
+    | UnauthorizedError
+    | ForbiddenError
+    | NotFoundError
+    | ConflictError
+    | PreconditionFailedError
+    | PreconditionRequiredError
+    | InternalServerError;
+
+  @doc("Delete one saved query.")
+  @useAuth(QylDeleteKeyAuth)
+  @delete
+  @route("/{saved_query_id}")
+  delete(
+    ...ProjectScopeHeader,
+    ...IfMatchHeader,
+    @path("saved_query_id") savedQueryId: ResourceId,
+  ):
+    | NoContentResponse
+    | UnauthorizedError
+    | ForbiddenError
+    | NotFoundError
+    | PreconditionFailedError
+    | PreconditionRequiredError
+    | InternalServerError;
+
+  @doc("Evaluate a saved query against current telemetry. Read-only.")
+  @useAuth(QylApiKeyHeaderAuth)
+  @post
+  @route("/{saved_query_id}:run")
+  run(
+    ...ProjectScopeHeader,
+    @path("saved_query_id") savedQueryId: ResourceId,
+    @body request: SavedQueryRunRequest,
+  ):
+    | SavedQueryRunResult
+    | ValidationError
+    | UnauthorizedError
+    | NotFoundError
+    | InternalServerError;
+}
+
 // -----------------------------------------------------------------------------
 // Health
 // -----------------------------------------------------------------------------

package/api/runner.tsp

@@ -22,6 +22,7 @@ namespace Qyl.Api.Contracts.Runner {
     message: RunnerLogLine,
   }
 
+  @doc("Served only by the local qyl runner on a loopback (127.0.0.1) listener. It rejects every request whose remote address or Host is not loopback, and checks the Origin header only on the mutating restart and stop operations, so these operations carry no API-key authentication.")
   @route("/runner/resources")
   @tag("Runner resources")
   interface RunnerResourcesApi {
@@ -81,3 +82,4 @@ namespace Qyl.Api.Contracts.Runner {
       | InternalServerError;
   }
 }
+

package/common/auth.tsp

@@ -0,0 +1,20 @@
+// =============================================================================
+// Collector key security schemes per role
+// =============================================================================
+// Every collector key travels in `x-otlp-api-key`; its roles
+// (Qyl.Api.Contracts.Common.CollectorKeyRole) decide what it may do. The query
+// routes keep the original `ApiKeyAuth` scheme and require the `read` role;
+// the schemes below name the roles the write routes require.
+// =============================================================================
+
+import "@typespec/http";
+
+using TypeSpec.Http;
+
+namespace TypeSpec.Http {
+  @doc("Collector API key in `x-otlp-api-key` carrying the `write` role (Qyl.Api.Contracts.Common.CollectorKeyRole). Creates and updates user resources.")
+  model QylWriteKeyAuth is ApiKeyAuth<ApiKeyLocation.header, "x-otlp-api-key">;
+
+  @doc("Collector API key in `x-otlp-api-key` carrying the `delete` role (Qyl.Api.Contracts.Common.CollectorKeyRole). Deletes user resources, never telemetry.")
+  model QylDeleteKeyAuth is ApiKeyAuth<ApiKeyLocation.header, "x-otlp-api-key">;
+}

package/common/errors.tsp

@@ -130,6 +130,28 @@ model ConflictError extends ProblemDetails {
   conflictingResource?: string;
 }
 
+@doc("Precondition failed - the If-Match entity tag is no longer current (412)")
+@error
+model PreconditionFailedError extends ProblemDetails {
+  @statusCode _: 412;
+  title: "Precondition Failed";
+
+  @doc("Entity tag of the current version, when the caller may read it")
+  @encodedName("application/json", "current_etag")
+  currentEtag?: string;
+}
+
+@doc("Precondition required - the request must send If-Match (428)")
+@error
+model PreconditionRequiredError extends ProblemDetails {
+  @statusCode _: 428;
+  title: "Precondition Required";
+
+  @doc("The header the request must carry")
+  @encodedName("application/json", "required_header")
+  requiredHeader?: "If-Match";
+}
+
 @doc("Rate limited - too many requests (429)")
 @error
 model RateLimitError extends ProblemDetails {
@@ -209,6 +231,12 @@ union ApiError {
   @doc("Resource conflict")
   conflict: ConflictError,
 
+  @doc("Entity tag no longer current")
+  preconditionFailed: PreconditionFailedError,
+
+  @doc("If-Match missing")
+  preconditionRequired: PreconditionRequiredError,
+
   @doc("Rate limit exceeded")
   rateLimit: RateLimitError,
 

package/common/resource.tsp

@@ -0,0 +1,106 @@
+// =============================================================================
+// Shared write base for user-created collector resources
+// =============================================================================
+// Every resource a client creates through the collector API (annotations, saved
+// queries) extends `ResourceBase`, and every write operation uses the headers
+// below. Server-assigned members carry `Lifecycle.Read` visibility, so the
+// create and update request models never accept them.
+//
+// Concurrency: a read returns `etag`; PATCH and DELETE send it back in
+// `If-Match`. A missing `If-Match` is refused with 428, a stale one with 412.
+// Retries: a POST that creates a resource takes `Idempotency-Key`; a repeat
+// with the same key and body returns the first result instead of a duplicate.
+// =============================================================================
+
+import "@typespec/http";
+import "./types.tsp";
+
+using TypeSpec.Http;
+
+namespace Qyl.Api.Contracts.Common;
+
+@doc("Opaque, server-assigned identifier of a user-created collector resource.")
+@minLength(1)
+@maxLength(128)
+scalar ResourceId extends string;
+
+@doc("""
+  Opaque entity tag of one resource version. It changes on every successful
+  update; send it back in `If-Match` to update or delete that version.
+  """)
+@minLength(1)
+@maxLength(128)
+scalar ETag extends string;
+
+@doc("""
+  Opaque pagination cursor. Pass the `next_cursor` of one page to receive the
+  next page of the same query. Its content is not part of the contract and
+  must not be parsed or built by a client.
+  """)
+scalar Cursor extends string;
+
+@doc("""
+  Collector API key roles. Every key sent in `x-otlp-api-key` carries one or
+  more roles: `ingest` accepts OTLP, `read` serves the query routes, `write`
+  creates and updates user resources, and `delete` deletes them. Roles are
+  independent, so a leaked ingest key can neither read, change nor delete
+  anything.
+  """)
+enum CollectorKeyRole {
+  @doc("Send OTLP traces, logs and metrics.")
+  ingest: "ingest",
+
+  @doc("Read telemetry and user resources.")
+  read: "read",
+
+  @doc("Create and update annotations and saved queries.")
+  write: "write",
+
+  @doc("Delete annotations and saved queries. Never deletes telemetry; retention does.")
+  delete: "delete",
+}
+
+@doc("Base of every user-created collector resource.")
+model ResourceBase {
+  @doc("Server-assigned identifier.")
+  @visibility(Lifecycle.Read)
+  id: ResourceId;
+
+  @doc("When the resource was created.")
+  @visibility(Lifecycle.Read)
+  @encodedName("application/json", "created_at")
+  createdAt: utcDateTime;
+
+  @doc("When the resource was last changed.")
+  @visibility(Lifecycle.Read)
+  @encodedName("application/json", "updated_at")
+  updatedAt: utcDateTime;
+
+  @doc("Entity tag of this version; also served as the `ETag` response header.")
+  @visibility(Lifecycle.Read)
+  etag: ETag;
+}
+
+@doc("Retry key for a creating POST.")
+model IdempotencyKeyHeader {
+  @doc("""
+    Client-chosen retry key, unique per intended create. A repeat with the same
+    key and body returns the first result; the same key with a different body
+    is refused with 409. Keys expire after 24 hours.
+    """)
+  @header("Idempotency-Key")
+  @minLength(1)
+  @maxLength(255)
+  idempotencyKey?: string;
+}
+
+@doc("Optimistic-concurrency precondition for PATCH and DELETE.")
+model IfMatchHeader {
+  @doc("""
+    The `etag` of the version being changed. A request without it is refused
+    with 428 Precondition Required; a request whose tag is no longer current is
+    refused with 412 Precondition Failed.
+    """)
+  @header("If-Match")
+  ifMatch: ETag;
+}