@ancplua/qyl-api-schema 0.2.0

package/api/streaming.tsp

@@ -0,0 +1,335 @@
+// =============================================================================
+// qyl streaming API routes
+// =============================================================================
+// Server-Sent Events (SSE) streaming endpoints for real-time telemetry.
+// =============================================================================
+
+import "@typespec/http";
+import "@typespec/sse";
+import "@typespec/events";
+import "@typespec/versioning";
+
+import "../common/types.tsp";
+import "../common/pagination.tsp";
+import "../otel/span.tsp";
+import "../otel/logs.tsp";
+import "../otel/metrics.tsp";
+import "../models/deployment.tsp";
+
+using TypeSpec.Http;
+using TypeSpec.SSE;
+using TypeSpec.Events;
+using TypeSpec.Versioning;
+
+using Qyl.Api.Contracts.Common;
+using Qyl.Api.Contracts.OTel.Traces;
+using Qyl.Api.Contracts.OTel.Logs;
+using Qyl.Api.Contracts.OTel.Metrics;
+using Qyl.Api.Contracts.OTel.Enums;
+using Qyl.Api.Contracts.Domains.Ops.Deployment;
+
+namespace Qyl.Api.Contracts.Streaming;
+
+// =============================================================================
+// Stream Event Types
+// =============================================================================
+
+@doc("Trace stream event")
+model TraceStreamEvent {
+  @doc("Event type")
+  type: "trace";
+
+  @doc("Trace data")
+  data: Trace;
+
+  @doc("Event timestamp")
+  timestamp: utcDateTime;
+}
+
+@doc("Span stream event")
+model SpanStreamEvent {
+  @doc("Event type")
+  type: "span";
+
+  @doc("Span data")
+  data: Span;
+
+  @doc("Event timestamp")
+  timestamp: utcDateTime;
+}
+
+@doc("Log stream event")
+model LogStreamEvent {
+  @doc("Event type")
+  type: "log";
+
+  @doc("Log data")
+  data: LogRecord;
+
+  @doc("Event timestamp")
+  timestamp: utcDateTime;
+}
+
+@doc("Metric stream event")
+model MetricStreamEvent {
+  @doc("Event type")
+  type: "metric";
+
+  @doc("Metric data")
+  data: Metric;
+
+  @doc("Event timestamp")
+  timestamp: utcDateTime;
+}
+
+@doc("Deployment stream event")
+model DeploymentStreamEvent {
+  @doc("Event type")
+  type: "deployment";
+
+  @doc("Deployment event data")
+  data: DeploymentEvent;
+
+  @doc("Event timestamp")
+  timestamp: utcDateTime;
+}
+
+@doc("Heartbeat event for connection keep-alive")
+model HeartbeatEvent {
+  @doc("Event type")
+  type: "heartbeat";
+
+  @doc("Server timestamp")
+  timestamp: utcDateTime;
+}
+
+// =============================================================================
+// Combined Stream Event Union
+// =============================================================================
+
+@doc("All possible stream event types")
+@events
+union TelemetryStreamEvent {
+  trace: TraceStreamEvent,
+  span: SpanStreamEvent,
+  log: LogStreamEvent,
+  metric: MetricStreamEvent,
+  deployment: DeploymentStreamEvent,
+  heartbeat: HeartbeatEvent,
+}
+
+@doc("Trace stream events")
+@events
+union TraceEvents {
+  trace: TraceStreamEvent,
+  heartbeat: HeartbeatEvent,
+}
+
+@doc("Span stream events")
+@events
+union SpanEvents {
+  span: SpanStreamEvent,
+  heartbeat: HeartbeatEvent,
+}
+
+@doc("Log stream events")
+@events
+union LogEvents {
+  log: LogStreamEvent,
+  heartbeat: HeartbeatEvent,
+}
+
+@doc("Metric stream events")
+@events
+union MetricEvents {
+  metric: MetricStreamEvent,
+  heartbeat: HeartbeatEvent,
+}
+
+@doc("Deployment stream events")
+@events
+union DeploymentEvents {
+  deployment: DeploymentStreamEvent,
+  heartbeat: HeartbeatEvent,
+}
+
+// =============================================================================
+// Stream Subscription Models
+// =============================================================================
+
+@doc("Stream subscription request")
+model StreamSubscription {
+  @doc("Event types to subscribe to")
+  @encodedName("application/json", "event_types")
+  eventTypes: StreamEventType[];
+
+  @doc("Service name filter")
+  @encodedName("application/json", "service_name")
+  serviceName?: string;
+
+  @doc("Trace ID filter (for specific trace)")
+  @encodedName("application/json", "trace_id")
+  traceId?: TraceId;
+
+  @doc("Minimum severity for logs (1-24)")
+  @encodedName("application/json", "min_severity")
+  @minValue(1)
+  @maxValue(24)
+  minSeverity?: int32;
+
+  @doc("Attribute filters")
+  filters?: Record<string>;
+
+  @doc("Sample rate (0.0-1.0)")
+  @encodedName("application/json", "sample_rate")
+  @minValue(0)
+  @maxValue(1)
+  sampleRate?: float64;
+}
+
+@doc("Stream event types")
+enum StreamEventType {
+  @doc("Trace events")
+  traces: "traces",
+
+  @doc("Span events")
+  spans: "spans",
+
+  @doc("Log events")
+  logs: "logs",
+
+  @doc("Metric events")
+  metrics: "metrics",
+
+  @doc("Deployment events")
+  deployments: "deployments",
+
+  @doc("All events")
+  all: "all",
+}
+
+// =============================================================================
+// Streaming API Interfaces
+// =============================================================================
+
+@route("/api/v1/stream")
+@tag("Streaming")
+interface StreamingApi {
+  @doc("Stream all telemetry events (SSE)")
+  @get
+  @route("/events")
+  streamEvents(
+    @query @doc("Event types") types?: StreamEventType[],
+    @query @doc("Service name filter") serviceName?: string,
+    @query @doc("Sample rate") sampleRate?: float64,
+  ): SSEStream<TelemetryStreamEvent>;
+
+  @doc("Stream traces in real-time")
+  @get
+  @route("/traces")
+  streamTraces(
+    @query @doc("Service name filter") serviceName?: string,
+    @query @doc("Minimum duration filter") minDurationMs?: int64,
+  ): SSEStream<TraceEvents>;
+
+  @doc("Stream spans for a specific trace")
+  @get
+  @route("/traces/{traceId}/spans")
+  streamTraceSpans(@path traceId: TraceId): SSEStream<SpanEvents>;
+
+  @doc("Stream logs in real-time")
+  @get
+  @route("/logs")
+  streamLogs(
+    @query @doc("Service name filter") serviceName?: string,
+    @query @doc("Minimum severity") minSeverity?: int32,
+    @query @doc("Query filter") query?: string,
+  ): SSEStream<LogEvents>;
+
+  @doc("Stream metrics in real-time")
+  @get
+  @route("/metrics")
+  streamMetrics(
+    @query @doc("Metric name filter") metricName?: string,
+    @query @doc("Service name filter") serviceName?: string,
+  ): SSEStream<MetricEvents>;
+
+  @doc("Stream deployment events")
+  @get
+  @route("/deployments")
+  streamDeployments(
+    @query @doc("Service name filter") serviceName?: string,
+    @query @doc("Environment filter") environment?: string,
+  ): SSEStream<DeploymentEvents>;
+}
+
+// =============================================================================
+// WebSocket Streaming (Alternative)
+// =============================================================================
+
+@doc("WebSocket message wrapper")
+model WebSocketMessage<T> {
+  @doc("Message ID")
+  id: string;
+
+  @doc("Message type")
+  type: WebSocketMessageType;
+
+  @doc("Message payload")
+  payload?: T;
+
+  @doc("Timestamp")
+  timestamp: utcDateTime;
+}
+
+@doc("WebSocket message types")
+enum WebSocketMessageType {
+  @doc("Subscribe to events")
+  subscribe: "subscribe",
+
+  @doc("Unsubscribe from events")
+  unsubscribe: "unsubscribe",
+
+  @doc("Data event")
+  data: "data",
+
+  @doc("Error message")
+  error: "error",
+
+  @doc("Acknowledgment")
+  ack: "ack",
+
+  @doc("Ping")
+  ping: "ping",
+
+  @doc("Pong")
+  pong: "pong",
+}
+
+// =============================================================================
+// Tail-based Sampling Configuration
+// =============================================================================
+
+@doc("Tail-based sampling configuration for streaming")
+model TailSamplingConfig {
+  @doc("Enable tail-based sampling")
+  enabled: boolean;
+
+  @doc("Sample error traces")
+  @encodedName("application/json", "sample_errors")
+  sampleErrors: boolean;
+
+  @doc("Sample slow traces (above threshold)")
+  @encodedName("application/json", "sample_slow")
+  sampleSlow: boolean;
+
+  @doc("Slow trace threshold in milliseconds")
+  @encodedName("application/json", "slow_threshold_ms")
+  slowThresholdMs?: int64;
+
+  @doc("Random sample rate for remaining traces")
+  @encodedName("application/json", "random_rate")
+  @minValue(0)
+  @maxValue(1)
+  randomRate: float64;
+}

package/common/errors.tsp

@@ -0,0 +1,206 @@
+// =============================================================================
+// ANcpLua v2.0 - Error Models
+// =============================================================================
+// Standardized error responses following RFC 7807 Problem Details.
+// =============================================================================
+
+import "@typespec/http";
+
+using TypeSpec.Http;
+
+namespace Qyl.Api.Contracts.Common.Errors;
+
+// =============================================================================
+// RFC 7807 Problem Details Base
+// =============================================================================
+
+@doc("RFC 7807 Problem Details for HTTP APIs")
+@error
+model ProblemDetails {
+  @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")
+  title: string;
+
+  @doc("The HTTP status code (informational only, actual code set by subtype)")
+  status: int32;
+
+  @doc("A human-readable explanation specific to this occurrence")
+  detail?: string;
+
+  @doc("A URI reference identifying the specific occurrence")
+  instance?: url;
+
+  @doc("Trace ID for correlation")
+  @encodedName("application/json", "trace_id")
+  @header("X-Trace-Id")
+  traceId?: string;
+
+  @doc("Request ID for support")
+  @encodedName("application/json", "request_id")
+  @header("X-Request-Id")
+  requestId?: string;
+
+  @doc("Timestamp of the error")
+  timestamp?: utcDateTime;
+}
+
+// =============================================================================
+// Specific Error 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)")
+@error
+model ValidationError extends ProblemDetails {
+  @statusCode _: 400;
+  title: "Validation Failed";
+
+  @doc("List of validation errors")
+  errors: ValidationErrorDetail[];
+}
+
+@doc("Individual validation error detail")
+model ValidationErrorDetail {
+  @doc("The field/property that failed validation")
+  field: string;
+
+  @doc("The error message")
+  message: string;
+
+  @doc("The validation rule that failed")
+  code: string;
+
+  @doc("The rejected value (if safe to include)")
+  @encodedName("application/json", "rejected_value")
+  rejectedValue?: string;
+}
+
+@doc("Unauthorized - authentication required (401)")
+@error
+model UnauthorizedError extends ProblemDetails {
+  @statusCode _: 401;
+  title: "Unauthorized";
+
+  @doc("Authentication scheme expected")
+  @header("WWW-Authenticate")
+  @encodedName("application/json", "www_authenticate")
+  wwwAuthenticate?: string;
+}
+
+@doc("Forbidden - insufficient permissions (403)")
+@error
+model ForbiddenError extends ProblemDetails {
+  @statusCode _: 403;
+  title: "Forbidden";
+
+  @doc("Required permission that is missing")
+  @encodedName("application/json", "required_permission")
+  requiredPermission?: string;
+}
+
+@doc("Conflict - resource state conflict (409)")
+@error
+model ConflictError extends ProblemDetails {
+  @statusCode _: 409;
+  title: "Conflict";
+
+  @doc("The conflicting resource ID")
+  @encodedName("application/json", "conflicting_resource")
+  conflictingResource?: string;
+}
+
+@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)")
+@error
+model InternalServerError extends ProblemDetails {
+  @statusCode _: 500;
+  title: "Internal Server Error";
+
+  @doc("Error code for support reference")
+  @encodedName("application/json", "error_code")
+  errorCode?: string;
+}
+
+@doc("Service unavailable (503)")
+@error
+model ServiceUnavailableError extends ProblemDetails {
+  @statusCode _: 503;
+  title: "Service Unavailable";
+
+  @doc("Expected availability time")
+  @header("Retry-After")
+  @encodedName("application/json", "retry_after")
+  retryAfter?: int32;
+
+  @doc("Reason for unavailability")
+  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("Rate limit exceeded")
+  rateLimit: RateLimitError,
+
+  @doc("Server error")
+  serverError: InternalServerError,
+
+  @doc("Service unavailable")
+  unavailable: ServiceUnavailableError,
+}