@ancplua/qyl-api-schema 0.2.0

package/models/rpc.tsp

@@ -0,0 +1,309 @@
+// =============================================================================
+// ANcpLua v2.0 - RPC Semantic Conventions (OTel v1.40)
+// =============================================================================
+// Remote Procedure Call telemetry attributes (gRPC, etc.).
+// =============================================================================
+
+import "../common/types.tsp";
+
+using Qyl.Api.Contracts.Common;
+
+namespace Qyl.Api.Contracts.Domains.Transport.Rpc;
+
+// =============================================================================
+// RPC Span Attributes
+// =============================================================================
+
+@doc("RPC span attributes")
+model RpcAttributes {
+  @doc("The RPC system (e.g., grpc, wcf, java_rmi)")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.System)
+  system: RpcSystem;
+
+  @doc("The RPC service name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.Service)
+  service?: string;
+
+  @doc("The RPC method name")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.Method)
+  method?: string;
+
+  @doc("Server address")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Server.Address)
+  serverAddress?: string;
+
+  @doc("Server port")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Server.Port)
+  serverPort?: Port;
+
+  // ---------------------------------------------------------------------------
+  // gRPC-Specific Attributes
+  // ---------------------------------------------------------------------------
+
+  @doc("gRPC status code")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.GrpcStatusCode)
+  grpcStatusCode?: GrpcStatusCode;
+
+  @doc("gRPC request metadata. Keys map to rpc.grpc.request.metadata.<key>")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.GrpcRequestMetadata)
+  grpcRequestMetadata?: Record<string[]>;
+
+  @doc("gRPC response metadata. Keys map to rpc.grpc.response.metadata.<key>")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.GrpcResponseMetadata)
+  grpcResponseMetadata?: Record<string[]>;
+
+  // ---------------------------------------------------------------------------
+  // Message Attributes
+  // ---------------------------------------------------------------------------
+
+  @doc("Message type (SENT or RECEIVED)")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.MessageType)
+  messageType?: RpcMessageType;
+
+  @doc("Message ID (sequence number)")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.MessageId)
+  messageId?: int64;
+
+  @doc("Compressed message size in bytes")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.MessageCompressedSize)
+  messageCompressedSize?: ByteSize;
+
+  @doc("Uncompressed message size in bytes")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.MessageUncompressedSize)
+  messageUncompressedSize?: ByteSize;
+
+  // ---------------------------------------------------------------------------
+  // Connect RPC Attributes
+  // ---------------------------------------------------------------------------
+
+  @doc("Connect RPC error code")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.ConnectRpcErrorCode)
+  connectRpcErrorCode?: ConnectRpcErrorCode;
+
+  // ---------------------------------------------------------------------------
+  // JSON-RPC Attributes
+  // ---------------------------------------------------------------------------
+
+  @doc("JSON-RPC error code")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.JsonrpcErrorCode)
+  jsonrpcErrorCode?: int32;
+
+  @doc("JSON-RPC error message")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.JsonrpcErrorMessage)
+  jsonrpcErrorMessage?: string;
+
+  @doc("JSON-RPC request ID")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.JsonrpcRequestId)
+  jsonrpcRequestId?: string;
+
+  @doc("JSON-RPC version")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.JsonrpcVersion)
+  jsonrpcVersion?: string;
+}
+
+// =============================================================================
+// RPC Enumerations
+// =============================================================================
+
+@doc("RPC systems")
+enum RpcSystem {
+  @doc("gRPC protocol")
+  grpc: "grpc",
+
+  @doc("Apache Thrift")
+  apacheThrift: "apache_thrift",
+
+  @doc("Connect RPC")
+  connectRpc: "connect_rpc",
+
+  @doc("JSON-RPC")
+  jsonrpc: "jsonrpc",
+
+  @doc("Apache Dubbo")
+  apacheDubbo: "apache_dubbo",
+
+  @doc("Windows Communication Foundation")
+  wcf: "wcf",
+
+  @doc("Java RMI")
+  javaRmi: "java_rmi",
+
+  @doc(".NET Remoting")
+  dotnetRemoting: "dotnet_remoting",
+}
+
+@doc("gRPC status codes")
+enum GrpcStatusCode {
+  @doc("Success")
+  ok: 0,
+
+  @doc("Cancelled by client")
+  cancelled: 1,
+
+  @doc("Unknown error")
+  `unknown`: 2,
+
+  @doc("Invalid argument")
+  invalidArgument: 3,
+
+  @doc("Deadline exceeded")
+  deadlineExceeded: 4,
+
+  @doc("Not found")
+  notFound: 5,
+
+  @doc("Already exists")
+  alreadyExists: 6,
+
+  @doc("Permission denied")
+  permissionDenied: 7,
+
+  @doc("Resource exhausted")
+  resourceExhausted: 8,
+
+  @doc("Failed precondition")
+  failedPrecondition: 9,
+
+  @doc("Aborted")
+  aborted: 10,
+
+  @doc("Out of range")
+  outOfRange: 11,
+
+  @doc("Unimplemented")
+  unimplemented: 12,
+
+  @doc("Internal error")
+  internal: 13,
+
+  @doc("Unavailable")
+  unavailable: 14,
+
+  @doc("Data loss")
+  dataLoss: 15,
+
+  @doc("Unauthenticated")
+  unauthenticated: 16,
+}
+
+@doc("Connect RPC error codes")
+enum ConnectRpcErrorCode {
+  @doc("Cancelled")
+  cancelled: "cancelled",
+
+  @doc("Unknown")
+  `unknown`: "unknown",
+
+  @doc("Invalid argument")
+  invalidArgument: "invalid_argument",
+
+  @doc("Deadline exceeded")
+  deadlineExceeded: "deadline_exceeded",
+
+  @doc("Not found")
+  notFound: "not_found",
+
+  @doc("Already exists")
+  alreadyExists: "already_exists",
+
+  @doc("Permission denied")
+  permissionDenied: "permission_denied",
+
+  @doc("Resource exhausted")
+  resourceExhausted: "resource_exhausted",
+
+  @doc("Failed precondition")
+  failedPrecondition: "failed_precondition",
+
+  @doc("Aborted")
+  aborted: "aborted",
+
+  @doc("Out of range")
+  outOfRange: "out_of_range",
+
+  @doc("Unimplemented")
+  unimplemented: "unimplemented",
+
+  @doc("Internal")
+  internal: "internal",
+
+  @doc("Unavailable")
+  unavailable: "unavailable",
+
+  @doc("Data loss")
+  dataLoss: "data_loss",
+
+  @doc("Unauthenticated")
+  unauthenticated: "unauthenticated",
+}
+
+@doc("RPC message types")
+enum RpcMessageType {
+  @doc("Message sent")
+  sent: "SENT",
+
+  @doc("Message received")
+  received: "RECEIVED",
+}
+
+// =============================================================================
+// RPC Metrics
+// =============================================================================
+
+@doc("RPC server duration metric")
+model RpcServerDurationMetric {
+  @doc("Metric name")
+  name: "rpc.server.duration";
+
+  @doc("Metric unit (seconds)")
+  unit: "s";
+
+  @doc("RPC system")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.System)
+  system: RpcSystem;
+
+  @doc("RPC service")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.Service)
+  service: string;
+
+  @doc("RPC method")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.Method)
+  method: string;
+
+  @doc("gRPC status code")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.GrpcStatusCode)
+  grpcStatusCode?: GrpcStatusCode;
+}
+
+@doc("RPC client duration metric")
+model RpcClientDurationMetric {
+  @doc("Metric name")
+  name: "rpc.client.duration";
+
+  @doc("Metric unit (seconds)")
+  unit: "s";
+
+  @doc("RPC system")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.System)
+  system: RpcSystem;
+
+  @doc("RPC service")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.Service)
+  service: string;
+
+  @doc("RPC method")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.Method)
+  method: string;
+
+  @doc("Server address")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Server.Address)
+  serverAddress: string;
+
+  @doc("Server port")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Server.Port)
+  serverPort: Port;
+
+  @doc("gRPC status code")
+  @encodedName("application/json", ANcpLua.OpenTelemetry.SemanticConventions.Keys.Rpc.GrpcStatusCode)
+  grpcStatusCode?: GrpcStatusCode;
+}

package/models/search.tsp

@@ -0,0 +1,243 @@
+// =============================================================================
+// ANcpLua v2.0 - Unified Search Entities
+// =============================================================================
+// Search documents, inverted index, query telemetry.
+// =============================================================================
+
+import "@typespec/openapi";
+import "../common/types.tsp";
+
+using TypeSpec.OpenAPI;
+using Qyl.Api.Contracts.Common;
+
+namespace Qyl.Api.Contracts.Domains.Search;
+
+// =============================================================================
+// Search Document
+// =============================================================================
+
+@doc("Canonical search document across all entity types")
+@extension("x-csharp-type", "SearchDocumentEntity")
+model SearchDocumentEntity {
+  @doc("Document ID")
+  @key
+  id: string;
+
+  @doc("Source entity type (span, log, issue, workflow, etc.)")
+  @encodedName("application/json", "entity_type")
+  entityType: SearchEntityType;
+
+  @doc("Source entity ID")
+  @encodedName("application/json", "entity_id")
+  entityId: string;
+
+  @doc("Owning project")
+  @encodedName("application/json", "project_id")
+  projectId?: string;
+
+  @doc("Document title")
+  title: string;
+
+  @doc("Document body (searchable text)")
+  body?: string;
+
+  @doc("Link to source entity")
+  url?: string;
+
+  @doc("Document tags")
+  @encodedName("application/json", "tags_json")
+  tagsJson?: string;
+
+  @doc("Additional metadata")
+  @encodedName("application/json", "metadata_json")
+  metadataJson?: string;
+
+  @doc("Relevance boost factor")
+  boost: float64;
+
+  @doc("Last indexed timestamp")
+  @encodedName("application/json", "indexed_at")
+  indexedAt: utcDateTime;
+
+  @doc("Last update timestamp")
+  @encodedName("application/json", "updated_at")
+  updatedAt: utcDateTime;
+}
+
+@doc("Searchable entity types")
+enum SearchEntityType {
+  @doc("Trace/span")
+  span: "span",
+
+  @doc("Log entry")
+  log: "log",
+
+  @doc("Error issue")
+  issue: "issue",
+
+  @doc("Workflow run")
+  workflow: "workflow",
+
+  @doc("Deployment")
+  deployment: "deployment",
+
+  @doc("Session")
+  session: "session",
+
+  @doc("Alert")
+  alert: "alert",
+
+  @doc("Fix run")
+  fix: "fix",
+}
+
+// =============================================================================
+// Search Term (Inverted Index)
+// =============================================================================
+
+@doc("Inverted token index entry")
+@extension("x-csharp-type", "SearchTermEntity")
+model SearchTermEntity {
+  @doc("Normalized term")
+  term: string;
+
+  @doc("Document containing this term")
+  @encodedName("application/json", "document_id")
+  documentId: string;
+
+  @doc("Field where term appears (title, body, tags)")
+  field: string;
+
+  @doc("Term frequency in this document/field")
+  @encodedName("application/json", "term_frequency")
+  termFrequency: int32;
+
+  @doc("Position offsets for highlighting")
+  @encodedName("application/json", "position_offsets_json")
+  positionOffsetsJson?: string;
+}
+
+// =============================================================================
+// Search Query Audit
+// =============================================================================
+
+@doc("Search query telemetry entry")
+@extension("x-csharp-type", "SearchQueryAuditEntity")
+model SearchQueryAuditEntity {
+  @doc("Audit entry ID")
+  @key
+  id: string;
+
+  @doc("Search query text")
+  @encodedName("application/json", "query_text")
+  queryText: string;
+
+  @doc("Query type")
+  @encodedName("application/json", "query_type")
+  queryType: string;
+
+  @doc("Filtered entity types")
+  @encodedName("application/json", "entity_types_json")
+  entityTypesJson?: string;
+
+  @doc("Project scope")
+  @encodedName("application/json", "project_id")
+  projectId?: string;
+
+  @doc("Number of results returned")
+  @encodedName("application/json", "result_count")
+  resultCount: int32;
+
+  @doc("Clicked result document ID")
+  @encodedName("application/json", "clicked_result_id")
+  clickedResultId?: string;
+
+  @doc("Position of clicked result")
+  @encodedName("application/json", "clicked_position")
+  clickedPosition?: int32;
+
+  @doc("Query execution time in ms")
+  @encodedName("application/json", "duration_ms")
+  durationMs?: int32;
+
+  @doc("Querying user")
+  @encodedName("application/json", "user_id")
+  userId?: string;
+
+  @doc("Query timestamp")
+  timestamp: utcDateTime;
+}
+
+// =============================================================================
+// Search Request/Response (API models, not stored)
+// =============================================================================
+
+@doc("Unified search request")
+model SearchRequest {
+  @doc("Search query text")
+  query: string;
+
+  @doc("Entity type filters")
+  @encodedName("application/json", "entity_types")
+  entityTypes?: SearchEntityType[];
+
+  @doc("Project scope")
+  @encodedName("application/json", "project_id")
+  projectId?: string;
+
+  @doc("Maximum results")
+  @minValue(1)
+  @maxValue(100)
+  limit?: int32 = 20;
+
+  @doc("Cursor for pagination")
+  cursor?: string;
+}
+
+@doc("Unified search response")
+model SearchResponse {
+  @doc("Search results")
+  results: SearchResult[];
+
+  @doc("Total matching documents")
+  @encodedName("application/json", "total_count")
+  totalCount: int64;
+
+  @doc("Query execution time in ms")
+  @encodedName("application/json", "duration_ms")
+  durationMs: int32;
+
+  @doc("Next page cursor")
+  @encodedName("application/json", "next_cursor")
+  nextCursor?: string;
+
+  @doc("Search suggestions")
+  suggestions?: string[];
+}
+
+@doc("Individual search result")
+model SearchResult {
+  @doc("Document ID")
+  @encodedName("application/json", "document_id")
+  documentId: string;
+
+  @doc("Entity type")
+  @encodedName("application/json", "entity_type")
+  entityType: SearchEntityType;
+
+  @doc("Entity ID")
+  @encodedName("application/json", "entity_id")
+  entityId: string;
+
+  @doc("Result title")
+  title: string;
+
+  @doc("Result snippet with highlights")
+  snippet?: string;
+
+  @doc("Relevance score")
+  score: float64;
+
+  @doc("Link to entity")
+  url?: string;
+}