@ancplua/qyl-api-schema 11.6.0 → 12.0.0

package/common/errors.tsp

@@ -1,251 +1,224 @@
 // =============================================================================
-// qyl product API error models
+// qyl product API problem details (RFC 9457)
 // =============================================================================
-// Standardized error responses following RFC 7807 Problem Details.
+// Every error body is an RFC 9457 problem: the five standard members plus the
+// qyl extension member `code`. A problem type is named twice, by its `type` URI
+// and by its `code`, and each error model below fixes both, so a client branches
+// on either and never on `title` or `detail`.
+//
+// Bodies carry no HTTP headers. The media type is a property of the body type
+// (`@mediaTypeHint`), and a header an error response carries is declared on the
+// operations whose server sends it: `X-Trace-Id` on the collector's 500
+// (api/routes.tsp) and `WWW-Authenticate` on the workbench's 401
+// (api/workbench.tsp).
 // =============================================================================
 
 import "@typespec/http";
-import "./types.tsp";
 
 using TypeSpec.Http;
 
 namespace Qyl.Api.Contracts.Common.Errors;
 
+@doc("""
+  Problem type URI, the RFC 9457 `type` member: one per problem a qyl server
+  reports. `code` names the same problem type.
+  """)
+enum ProblemType {
+  validationFailed: "https://qyl.at/problems/validation-failed",
+  unauthorized: "https://qyl.at/problems/unauthorized",
+  forbidden: "https://qyl.at/problems/forbidden",
+  notFound: "https://qyl.at/problems/not-found",
+  conflict: "https://qyl.at/problems/conflict",
+  preconditionFailed: "https://qyl.at/problems/precondition-failed",
+  preconditionRequired: "https://qyl.at/problems/precondition-required",
+  internalError: "https://qyl.at/problems/internal-error",
+  badGateway: "https://qyl.at/problems/bad-gateway",
+  serviceUnavailable: "https://qyl.at/problems/service-unavailable",
+}
+
+@doc("""
+  Stable machine-readable code of a problem type, the qyl `code` extension
+  member. `type` names the same problem type as a URI.
+  """)
+enum ProblemCode {
+  validationFailed: "validation_failed",
+  unauthorized: "unauthorized",
+  forbidden: "forbidden",
+  notFound: "not_found",
+  conflict: "conflict",
+  preconditionFailed: "precondition_failed",
+  preconditionRequired: "precondition_required",
+  internalError: "internal_error",
+  badGateway: "bad_gateway",
+  serviceUnavailable: "service_unavailable",
+}
+
 // =============================================================================
-// RFC 7807 Problem Details Base
+// RFC 9457 Problem Details Base
 // =============================================================================
 
-@doc("RFC 7807 Problem Details for HTTP APIs")
+@doc("RFC 9457 problem details, served as application/problem+json: the standard members plus the qyl `code` extension.")
+@mediaTypeHint("application/problem+json")
 @error
 model ProblemDetails {
-  @doc("RFC 7807 problem-details response media type")
-  @header contentType: "application/problem+json";
+  @doc("URI of the problem type.")
+  type: ProblemType;
 
-  @doc("A URI reference identifying the problem type")
-  @encodedName("application/json", "type")
-  problemType: url = "about:blank";
-
-  @doc("A short, human-readable summary of the problem type")
+  @doc("Short summary of the problem type; the same for every occurrence.")
   title: string;
 
-  @doc("The HTTP status code (informational only, actual code set by subtype)")
+  @doc("HTTP status code of this response, repeated for the reader of the body.")
   status: int32;
 
-  @doc("A human-readable explanation specific to this occurrence")
+  @doc("Explanation specific to this occurrence.")
   detail?: string;
 
-  @doc("A URI reference identifying the specific occurrence")
+  @doc("URI reference identifying this occurrence.")
   instance?: url;
 
-  @doc("Trace ID for correlation")
-  @encodedName("application/json", "trace_id")
-  @header("X-Trace-Id")
-  traceId?: TraceId;
-
-  @doc("Request ID for support")
-  @encodedName("application/json", "request_id")
-  @header("X-Request-Id")
-  requestId?: string;
-
-  @doc("Timestamp of the error")
-  timestamp?: utcDateTime;
+  @doc("Stable code of the problem type.")
+  code: ProblemCode;
 }
 
 // =============================================================================
-// Specific Error Types
+// Problem Types
 // =============================================================================
 
-@doc("Resource not found (404)")
-@error
-model NotFoundError extends ProblemDetails {
-  @statusCode _: 404;
-  title: "Not Found";
-
-  @doc("The type of resource that was not found")
-  @encodedName("application/json", "resource_type")
-  resourceType?: string;
-
-  @doc("The identifier that was not found")
-  @encodedName("application/json", "resource_id")
-  resourceId?: string;
-}
-
-@doc("Bad request - validation failed (400)")
+@doc("The request failed validation (400).")
 @error
 model ValidationError extends ProblemDetails {
   @statusCode _: 400;
+  type: ProblemType.validationFailed;
+  code: ProblemCode.validationFailed;
   title: "Validation Failed";
 
-  @doc("List of validation errors")
+  @doc("Each rule the request broke.")
   errors: ValidationErrorDetail[];
 }
 
-@doc("Individual validation error detail")
+@doc("One rule a request broke.")
 model ValidationErrorDetail {
-  @doc("The field/property that failed validation")
+  @doc("The field or parameter that failed validation.")
   field: string;
 
-  @doc("The error message")
+  @doc("What is wrong with it.")
   message: string;
 
-  @doc("The validation rule that failed")
+  @doc("The validation rule that failed.")
   code: string;
 
-  @doc("The rejected value (if safe to include)")
+  @doc("The rejected value, when it is safe to repeat.")
   @encodedName("application/json", "rejected_value")
   rejectedValue?: string;
 }
 
-@doc("Unauthorized - authentication required (401)")
+@doc("The request carries no valid credential (401).")
 @error
 model UnauthorizedError extends ProblemDetails {
   @statusCode _: 401;
+  type: ProblemType.unauthorized;
+  code: ProblemCode.unauthorized;
   title: "Unauthorized";
-
-  @doc("Authentication scheme expected")
-  @header("WWW-Authenticate")
-  @encodedName("application/json", "www_authenticate")
-  wwwAuthenticate?: string;
 }
 
-@doc("Forbidden - insufficient permissions (403)")
+@doc("The credential is valid but not allowed to do this (403).")
 @error
 model ForbiddenError extends ProblemDetails {
   @statusCode _: 403;
+  type: ProblemType.forbidden;
+  code: ProblemCode.forbidden;
   title: "Forbidden";
 
-  @doc("Required permission that is missing")
+  @doc("The permission the credential lacks.")
   @encodedName("application/json", "required_permission")
   requiredPermission?: string;
 }
 
-@doc("Conflict - resource state conflict (409)")
+@doc("The addressed resource does not exist (404).")
+@error
+model NotFoundError extends ProblemDetails {
+  @statusCode _: 404;
+  type: ProblemType.notFound;
+  code: ProblemCode.notFound;
+  title: "Not Found";
+
+  @doc("The kind of resource that was not found.")
+  @encodedName("application/json", "resource_type")
+  resourceType?: string;
+
+  @doc("The identifier that was not found.")
+  @encodedName("application/json", "resource_id")
+  resourceId?: string;
+}
+
+@doc("The request conflicts with the current state of a resource (409).")
 @error
 model ConflictError extends ProblemDetails {
   @statusCode _: 409;
+  type: ProblemType.conflict;
+  code: ProblemCode.conflict;
   title: "Conflict";
 
-  @doc("The conflicting resource ID")
+  @doc("The identifier of the conflicting resource.")
   @encodedName("application/json", "conflicting_resource")
   conflictingResource?: string;
 }
 
-@doc("Precondition failed - the If-Match entity tag is no longer current (412)")
+@doc("The If-Match entity tag is no longer current (412).")
 @error
 model PreconditionFailedError extends ProblemDetails {
   @statusCode _: 412;
+  type: ProblemType.preconditionFailed;
+  code: ProblemCode.preconditionFailed;
   title: "Precondition Failed";
 
-  @doc("Entity tag of the current version, when the caller may read it")
+  @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)")
+@doc("The request must send If-Match (428).")
 @error
 model PreconditionRequiredError extends ProblemDetails {
   @statusCode _: 428;
+  type: ProblemType.preconditionRequired;
+  code: ProblemCode.preconditionRequired;
   title: "Precondition Required";
 
-  @doc("The header the request must carry")
+  @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 {
-  @statusCode _: 429;
-  title: "Too Many Requests";
-
-  @doc("Seconds until the rate limit resets")
-  @header("Retry-After")
-  @encodedName("application/json", "retry_after")
-  retryAfter: int32;
-
-  @doc("Maximum requests allowed per window")
-  @header("X-RateLimit-Limit")
-  @encodedName("application/json", "rate_limit")
-  rateLimit?: int32;
-
-  @doc("Remaining requests in current window")
-  @header("X-RateLimit-Remaining")
-  @encodedName("application/json", "rate_limit_remaining")
-  rateLimitRemaining?: int32;
-}
-
-@doc("Internal server error (500)")
+@doc("The server failed while handling the request (500).")
 @error
 model InternalServerError extends ProblemDetails {
   @statusCode _: 500;
+  type: ProblemType.internalError;
+  code: ProblemCode.internalError;
   title: "Internal Server Error";
-
-  @doc("Error code for support reference")
-  @encodedName("application/json", "error_code")
-  errorCode?: string;
 }
 
-@doc("Upstream dependency failed while fulfilling the request (502)")
+@doc("An upstream dependency failed while the server handled the request (502).")
 @error
 model BadGatewayError extends ProblemDetails {
   @statusCode _: 502;
+  type: ProblemType.badGateway;
+  code: ProblemCode.badGateway;
   title: "Bad Gateway";
 
-  @doc("Stable dependency category; never contains raw exception text")
+  @doc("Stable dependency category; never raw exception text.")
   dependency?: string;
 }
 
-@doc("Service unavailable (503)")
+@doc("The server cannot take the request at present (503).")
 @error
 model ServiceUnavailableError extends ProblemDetails {
   @statusCode _: 503;
+  type: ProblemType.serviceUnavailable;
+  code: ProblemCode.serviceUnavailable;
   title: "Service Unavailable";
 
-  @doc("Expected availability time")
-  @header("Retry-After")
-  @encodedName("application/json", "retry_after")
-  retryAfter?: int32;
-
-  @doc("Reason for unavailability")
+  @doc("Why the server is unavailable.")
   reason?: "maintenance" | "overloaded" | "dependency_failure";
 }
-
-// =============================================================================
-// Error Response Union
-// =============================================================================
-
-@doc("Standard error response types")
-union ApiError {
-  @doc("Resource not found")
-  notFound: NotFoundError,
-
-  @doc("Validation failed")
-  validation: ValidationError,
-
-  @doc("Authentication required")
-  unauthorized: UnauthorizedError,
-
-  @doc("Permission denied")
-  forbidden: ForbiddenError,
-
-  @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,
-
-  @doc("Server error")
-  serverError: InternalServerError,
-
-  @doc("Upstream dependency failed")
-  badGateway: BadGatewayError,
-
-  @doc("Service unavailable")
-  unavailable: ServiceUnavailableError,
-}

package/common/pagination.tsp

@@ -1,7 +1,11 @@
 // =============================================================================
-// Qyl API pagination templates
+// Qyl API cursor pagination
 // =============================================================================
-// Reusable pagination patterns for list operations.
+// Every list operation pages the same way: it is a `@list` operation, spreads
+// `CursorPageQuery` (one page-size rule, one cursor parameter) and answers a
+// page whose items carry `@pageItems` and whose opaque `Cursor` carries
+// `@continuationToken`. The cursor is a token the client passes back, never a
+// link it follows, and the last page omits it.
 // =============================================================================
 
 import "@typespec/http";
@@ -11,244 +15,37 @@ using TypeSpec.Http;
 
 namespace Qyl.Api.Contracts.Common.Pagination;
 
-// =============================================================================
-// Cursor-Based Pagination (Preferred for Large Datasets)
-// =============================================================================
+@doc("Page size of a list operation: at least 1 and at most 1000 items.")
+@minValue(1)
+@maxValue(1000)
+scalar PageLimit extends int32;
 
-@doc("Cursor-based pagination parameters")
-model CursorPaginationParams {
-  @doc("Opaque cursor for fetching the next page")
+// The query parameters of every list operation. An alias, not a model, so it
+// reaches the wire only as the parameters of the operations that spread it.
+alias CursorPageQuery = {
+  @doc("Page size; 100 when omitted.")
   @query
-  cursor?: string;
-
-  @doc("Maximum number of items to return (1-1000)")
-  @query
-  @minValue(1)
-  @maxValue(1000)
-  limit?: int32 = 100;
+  @pageSize
+  limit?: PageLimit = 100;
 
-  @doc("Sort direction")
+  @doc("The `next_cursor` of the previous page of the same query; omitted for the first page.")
   @query
-  order?: SortOrder = SortOrder.desc;
-}
-
-@doc("Sort order")
-enum SortOrder {
-  @doc("Ascending order (oldest first)")
-  asc,
-
-  @doc("Descending order (newest first)")
-  desc,
-}
+  @continuationToken
+  cursor?: Cursor;
+};
 
-@doc("Cursor-based paginated response wrapper")
+@doc("One page of a list operation.")
 model CursorPage<T> {
-  @doc("List of items in this page")
+  @doc("The items of this page.")
   @pageItems
   items: T[];
 
-  @doc("Cursor for the next page (null if no more pages)")
+  @doc("Cursor of the next page, passed back as the `cursor` query parameter. Absent on the last page.")
   @encodedName("application/json", "next_cursor")
-  @nextLink
-  nextCursor?: string;
-
-  @doc("Cursor for the previous page (null if first page)")
-  @encodedName("application/json", "prev_cursor")
-  prevCursor?: string;
-
-  @doc("Whether there are more items available")
-  @encodedName("application/json", "has_more")
-  hasMore: boolean;
-}
-
-// =============================================================================
-// Offset-Based Pagination (For Small/Medium Datasets)
-// =============================================================================
-
-@doc("Offset-based pagination parameters")
-model OffsetPaginationParams {
-  @doc("Page number (1-indexed)")
-  @query
-  @pageIndex
-  @minValue(1)
-  page?: int32 = 1;
-
-  @doc("Items per page (1-1000)")
-  @query("page_size")
-  @pageSize
-  @minValue(1)
-  @maxValue(1000)
-  @encodedName("application/json", "page_size")
-  pageSize?: int32 = 100;
-}
-
-@doc("Offset-based paginated response wrapper")
-model OffsetPage<T> {
-  @doc("List of items in this page")
-  @pageItems
-  items: T[];
-
-  @doc("Current page number")
-  page: int32;
-
-  @doc("Items per page")
-  @encodedName("application/json", "page_size")
-  pageSize: int32;
-
-  @doc("Total number of items across all pages")
-  @encodedName("application/json", "total_count")
-  totalCount: int64;
-
-  @doc("Total number of pages")
-  @encodedName("application/json", "total_pages")
-  totalPages: int32;
-
-  @doc("Whether there is a next page")
-  @encodedName("application/json", "has_next")
-  hasNext: boolean;
-
-  @doc("Whether there is a previous page")
-  @encodedName("application/json", "has_prev")
-  hasPrev: boolean;
-}
-
-// =============================================================================
-// Time-Range Pagination (For Time-Series Data)
-// =============================================================================
-
-@doc("Time-range based query parameters")
-model TimeRangeParams {
-  @doc("Start of time range (inclusive)")
-  @query("start_time")
-  @encodedName("application/json", "start_time")
-  startTime?: utcDateTime;
-
-  @doc("End of time range (exclusive)")
-  @query("end_time")
-  @encodedName("application/json", "end_time")
-  endTime?: utcDateTime;
-
-  @doc("Maximum number of items to return")
-  @query
-  @minValue(1)
-  @maxValue(10000)
-  limit?: int32 = 1000;
-}
-
-@doc("Time-range paginated response with continuation")
-model TimeRangePage<T> {
-  @doc("List of items in this page")
-  @pageItems
-  items: T[];
-
-  @doc("Actual start time of returned data")
-  @encodedName("application/json", "start_time")
-  startTime: utcDateTime;
-
-  @doc("Actual end time of returned data")
-  @encodedName("application/json", "end_time")
-  endTime: utcDateTime;
-
-  @doc("Continuation token for next time window")
-  @encodedName("application/json", "continuation_token")
   @continuationToken
-  continuationToken?: string;
+  nextCursor?: Cursor;
 
-  @doc("Whether there is more data in the time range")
+  @doc("Whether more items follow this page. `next_cursor` is present exactly when this is true.")
   @encodedName("application/json", "has_more")
   hasMore: boolean;
-
-  @doc("Number of items returned")
-  count: int32;
-}
-
-// =============================================================================
-// Streaming Pagination (For Real-Time Data)
-// =============================================================================
-
-@doc("Streaming parameters for SSE endpoints")
-model StreamParams {
-  @doc("Include historical data from this timestamp")
-  @query
-  since?: utcDateTime;
-
-  @doc("Filter by trace ID")
-  @query("trace_id")
-  @encodedName("application/json", "trace_id")
-  traceId?: TraceId;
-
-  @doc("Filter by service name")
-  @query("service_name")
-  @encodedName("application/json", "service_name")
-  serviceName?: string;
-
-  @doc("Maximum events per second (rate limiting)")
-  @query("max_events_per_second")
-  @encodedName("application/json", "max_events_per_second")
-  @minValue(1)
-  @maxValue(1000)
-  maxEventsPerSecond?: int32 = 100;
-}
-
-@doc("SSE event wrapper for streaming")
-model StreamEvent<T> {
-  @doc("Event ID for resumption")
-  id: string;
-
-  @doc("Event type")
-  @encodedName("application/json", "event_type")
-  eventType: string;
-
-  @doc("Event timestamp")
-  timestamp: utcDateTime;
-
-  @doc("Event data payload")
-  data: T;
-
-  @doc("Retry interval hint in milliseconds")
-  retry?: int32;
-}
-
-// =============================================================================
-// Aggregation Parameters
-// =============================================================================
-
-@doc("Time bucket size for aggregations")
-enum TimeBucket {
-  @doc("1 minute buckets")
-  minute: "1m",
-
-  @doc("5 minute buckets")
-  fiveMinutes: "5m",
-
-  @doc("15 minute buckets")
-  fifteenMinutes: "15m",
-
-  @doc("1 hour buckets")
-  hour: "1h",
-
-  @doc("1 day buckets")
-  day: "1d",
-
-  @doc("1 week buckets")
-  week: "1w",
-
-  @doc("Auto-select based on time range")
-  auto: "auto",
-}
-
-@doc("Aggregation query parameters")
-model AggregationParams {
-  @doc("Time bucket size")
-  @query
-  bucket?: TimeBucket = TimeBucket.auto;
-
-  @doc("Group by these dimensions")
-  @query("group_by")
-  @encodedName("application/json", "group_by")
-  groupBy?: string[];
-
-  @doc("Filter expression")
-  @query
-  filter?: string;
 }

package/common/resource.tsp

@@ -32,13 +32,6 @@ scalar ResourceId extends string;
 @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`

package/common/types.tsp

@@ -159,10 +159,18 @@ scalar Temperature extends float64;
 @maxLength(64)
 scalar Sha256Hash 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;
+
 // The revision is a canonical digest of the semantic OpenAPI projection and the
 // exported telemetry-key projection, not a package version. Presentation-only
-// fields do not change it. Truncated to 16 hex characters because it is compared
-// for equality, never used as a security boundary.
+// fields and the release version stamped into `info.version` do not change it.
+// Truncated to 16 hex characters because it is compared for equality, never used
+// as a security boundary.
 @doc("Deterministic revision of the generated API contract: 'sha256:' followed by the first 16 hex characters of its canonical semantic digest.")
 @pattern("^sha256:[a-f0-9]{16}$")
 @minLength(23)