@qlever-llc/trellis 0.8.4 → 0.9.0-rc.10

package/src/contract_support/protocol.ts

@@ -0,0 +1,213 @@
+import Type, { type Static, type TSchema } from "typebox";
+
+function parseIsoDate(value: string): Date {
+  const parsed = new Date(value);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString() !== value) {
+    throw new TypeError(
+      `Expected canonical ISO 8601 UTC date-time string, received '${value}'`,
+    );
+  }
+  return parsed;
+}
+
+function formatIsoDate(value: Date): string {
+  if (!(value instanceof Date) || Number.isNaN(value.getTime())) {
+    throw new TypeError("Expected a valid Date instance");
+  }
+  return value.toISOString();
+}
+
+export const ContractSchemaRefSchema = Type.Object({
+  schema: Type.String({ minLength: 1 }),
+});
+
+export type ContractSchemaRef = Static<typeof ContractSchemaRefSchema>;
+
+export const ContractKvResourceSchema = Type.Object({
+  purpose: Type.String({ minLength: 1 }),
+  schema: ContractSchemaRefSchema,
+  required: Type.Optional(Type.Boolean({ default: true })),
+  history: Type.Optional(Type.Integer({ minimum: 1, default: 1 })),
+  ttlMs: Type.Optional(Type.Integer({ minimum: 0, default: 0 })),
+  maxValueBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+
+export type ContractKvResource = Static<typeof ContractKvResourceSchema>;
+
+export const ContractStoreResourceSchema = Type.Object({
+  purpose: Type.String({ minLength: 1 }),
+  required: Type.Optional(Type.Boolean({ default: true })),
+  ttlMs: Type.Optional(Type.Integer({ minimum: 0, default: 0 })),
+  maxObjectBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+  maxTotalBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+
+export type ContractStoreResource = Static<typeof ContractStoreResourceSchema>;
+
+export const ContractStateStoreSchema = Type.Object({
+  kind: Type.Union([
+    Type.Literal("value"),
+    Type.Literal("map"),
+  ]),
+  schema: ContractSchemaRefSchema,
+  stateVersion: Type.Optional(Type.String({ minLength: 1 })),
+  acceptedVersions: Type.Optional(Type.Record(
+    Type.String({ minLength: 1 }),
+    ContractSchemaRefSchema,
+  )),
+});
+
+export type ContractStateStore = Static<typeof ContractStateStoreSchema>;
+
+export const ContractStateSchema = Type.Record(
+  Type.String({ minLength: 1 }),
+  ContractStateStoreSchema,
+);
+
+export type ContractState = Static<typeof ContractStateSchema>;
+
+export const ContractJobQueueSchema = Type.Object({
+  payload: ContractSchemaRefSchema,
+  result: Type.Optional(ContractSchemaRefSchema),
+  maxDeliver: Type.Optional(Type.Integer({ minimum: 1 })),
+  backoffMs: Type.Optional(Type.Array(Type.Integer({ minimum: 0 }))),
+  ackWaitMs: Type.Optional(Type.Integer({ minimum: 1 })),
+  defaultDeadlineMs: Type.Optional(Type.Integer({ minimum: 1 })),
+  progress: Type.Optional(Type.Boolean()),
+  logs: Type.Optional(Type.Boolean()),
+  dlq: Type.Optional(Type.Boolean()),
+  concurrency: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+
+export type ContractJobQueue = Static<typeof ContractJobQueueSchema>;
+
+export const ContractJobsSchema = Type.Record(
+  Type.String({ minLength: 1 }),
+  ContractJobQueueSchema,
+);
+
+export type ContractJobs = Static<typeof ContractJobsSchema>;
+
+export const ContractResourcesSchema = Type.Object({
+  kv: Type.Optional(
+    Type.Record(Type.String({ minLength: 1 }), ContractKvResourceSchema),
+  ),
+  store: Type.Optional(
+    Type.Record(Type.String({ minLength: 1 }), ContractStoreResourceSchema),
+  ),
+}, { additionalProperties: false });
+
+export type ContractResources = Static<typeof ContractResourcesSchema>;
+
+export const KvResourceBindingSchema = Type.Object({
+  bucket: Type.String({ minLength: 1 }),
+  history: Type.Integer({ minimum: 1 }),
+  ttlMs: Type.Integer({ minimum: 0 }),
+  maxValueBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+
+export type KvResourceBinding = Static<typeof KvResourceBindingSchema>;
+
+export const StoreResourceBindingSchema = Type.Object({
+  name: Type.String({ minLength: 1 }),
+  ttlMs: Type.Integer({ minimum: 0 }),
+  maxObjectBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+  maxTotalBytes: Type.Optional(Type.Integer({ minimum: 1 })),
+});
+
+export type StoreResourceBinding = Static<typeof StoreResourceBindingSchema>;
+
+export const JobsQueueBindingSchema = Type.Object({
+  queueType: Type.String({ minLength: 1 }),
+  publishPrefix: Type.String({ minLength: 1 }),
+  workSubject: Type.String({ minLength: 1 }),
+  consumerName: Type.String({ minLength: 1 }),
+  payload: ContractSchemaRefSchema,
+  result: Type.Optional(ContractSchemaRefSchema),
+  maxDeliver: Type.Integer({ minimum: 1 }),
+  backoffMs: Type.Array(Type.Integer({ minimum: 0 })),
+  ackWaitMs: Type.Integer({ minimum: 1 }),
+  defaultDeadlineMs: Type.Optional(Type.Integer({ minimum: 1 })),
+  progress: Type.Boolean(),
+  logs: Type.Boolean(),
+  dlq: Type.Boolean(),
+  concurrency: Type.Integer({ minimum: 1 }),
+});
+
+export type JobsQueueBinding = Static<typeof JobsQueueBindingSchema>;
+
+export const JobsResourceBindingSchema = Type.Object({
+  namespace: Type.String({ minLength: 1 }),
+  workStream: Type.Optional(Type.String({ minLength: 1 })),
+  queues: Type.Record(Type.String({ minLength: 1 }), JobsQueueBindingSchema),
+});
+
+export type JobsResourceBinding = Static<typeof JobsResourceBindingSchema>;
+
+export const ContractResourceBindingsSchema = Type.Object({
+  kv: Type.Optional(
+    Type.Record(Type.String({ minLength: 1 }), KvResourceBindingSchema),
+  ),
+  store: Type.Optional(
+    Type.Record(Type.String({ minLength: 1 }), StoreResourceBindingSchema),
+  ),
+  jobs: Type.Optional(JobsResourceBindingSchema),
+});
+
+export type ContractResourceBindings = Static<
+  typeof ContractResourceBindingsSchema
+>;
+
+export const InstalledServiceContractSchema = Type.Object({
+  contractId: Type.String({ minLength: 1 }),
+  digest: Type.String({ pattern: "^[A-Za-z0-9_-]+$" }),
+  resources: ContractResourceBindingsSchema,
+});
+
+export type InstalledServiceContract = Static<
+  typeof InstalledServiceContractSchema
+>;
+
+export const IsoDateSchema = Type.Codec(
+  Type.String({ format: "date-time" }),
+)
+  .Decode((value: string) => parseIsoDate(value))
+  .Encode((value: Date) => formatIsoDate(value));
+
+export const EventHeaderSchema = Type.Object({
+  header: Type.Object({
+    id: Type.String(),
+    time: IsoDateSchema,
+  }),
+});
+
+export type EventHeader = Static<typeof EventHeaderSchema>;
+
+/** Schema for a bounded pagination request. */
+export const PageRequestSchema = Type.Object({
+  offset: Type.Optional(Type.Integer({ minimum: 0 })),
+  limit: Type.Integer({ minimum: 0 }),
+});
+
+/** Bounded pagination request. */
+export type PageRequest = Static<typeof PageRequestSchema>;
+
+/** Create a schema for a bounded page response with typed entries. */
+export function PageResponseSchema<TEntry extends TSchema>(entry: TEntry) {
+  return Type.Object({
+    entries: Type.Array(entry, { default: [] }),
+    count: Type.Integer({ minimum: 0 }),
+    offset: Type.Integer({ minimum: 0 }),
+    limit: Type.Integer({ minimum: 0 }),
+    nextOffset: Type.Optional(Type.Integer({ minimum: 0 })),
+  });
+}
+
+/** Bounded pagination response with typed entries. */
+export type PageResponse<TEntry> = {
+  entries: TEntry[];
+  count: number;
+  offset: number;
+  limit: number;
+  nextOffset?: number;
+};

package/src/contract_support/runtime.ts

@@ -0,0 +1,129 @@
+import type { StaticDecode, TSchema } from "typebox";
+
+import type { BaseError } from "@qlever-llc/result";
+import type { SubjectParam } from "./schema_pointers.js";
+
+export type Schema<T> = {
+  schema: unknown;
+  readonly __trellisType?: T;
+};
+
+export type SchemaLike<T = unknown> = TSchema | Schema<T>;
+
+export type SerializableErrorData = {
+  id: string;
+  type: string;
+  message: string;
+  context?: Record<string, unknown>;
+  traceId?: string;
+} & Record<string, unknown>;
+
+export type RpcErrorClass<
+  TData extends SerializableErrorData = SerializableErrorData,
+  TError extends BaseError = BaseError,
+> = {
+  fromSerializable(data: TData): TError;
+};
+
+export type RuntimeRpcErrorDesc<
+  TType extends string = string,
+  TSchema extends SchemaLike | undefined = SchemaLike | undefined,
+  TError extends BaseError = BaseError,
+> = {
+  type: TType;
+  schema?: TSchema;
+  fromSerializable(
+    data: TSchema extends SchemaLike ? InferSchemaType<TSchema>
+      : SerializableErrorData,
+  ): TError;
+};
+
+export type InferRuntimeRpcError<T extends RuntimeRpcErrorDesc> = T extends
+  RuntimeRpcErrorDesc<string, SchemaLike | undefined, infer TError> ? TError
+  : never;
+
+export type InferSchemaType<S> = S extends Schema<infer T> ? T
+  : S extends TSchema ? StaticDecode<S>
+  : unknown;
+
+export function schema<T>(raw: unknown): Schema<T> {
+  return { schema: raw } as Schema<T>;
+}
+
+export function unwrapSchema(raw: SchemaLike): unknown {
+  if (raw && typeof raw === "object" && "schema" in raw) {
+    return (raw as Schema<unknown>).schema;
+  }
+  return raw;
+}
+
+export type RPCDesc<
+  I extends SchemaLike = SchemaLike,
+  O extends SchemaLike = SchemaLike,
+  E extends readonly string[] | undefined = readonly string[] | undefined,
+  TRuntimeErrors extends readonly RuntimeRpcErrorDesc[] | undefined =
+    | readonly RuntimeRpcErrorDesc[]
+    | undefined,
+> = {
+  subject: string;
+  input: I;
+  output: O;
+  callerCapabilities: readonly string[];
+  transfer?: { direction: "receive" };
+  authRequired?: boolean;
+  errors?: E;
+  runtimeErrors?: TRuntimeErrors;
+  declaredErrorTypes?: readonly string[];
+};
+
+export type EventDesc<S extends SchemaLike = SchemaLike> = {
+  subject: string;
+  params?: readonly SubjectParam[];
+  event: S;
+  publishCapabilities: readonly string[];
+  subscribeCapabilities: readonly string[];
+};
+
+export type FeedDesc<
+  I extends SchemaLike = SchemaLike,
+  E extends SchemaLike = SchemaLike,
+> = {
+  subject: string;
+  input: I;
+  event: E;
+  subscribeCapabilities: readonly string[];
+};
+
+export type OperationDesc<
+  I extends SchemaLike = SchemaLike,
+  P extends SchemaLike | undefined = SchemaLike | undefined,
+  O extends SchemaLike | undefined = SchemaLike | undefined,
+> = {
+  subject: string;
+  input: I;
+  progress?: P;
+  output?: O;
+  transfer?: {
+    direction: "send";
+    store: string;
+    key: `/${string}`;
+    contentType?: `/${string}`;
+    metadata?: `/${string}`;
+    expiresInMs?: number;
+    maxBytes?: number;
+  };
+  signals?: Record<string, { input: SchemaLike }>;
+  callerCapabilities: readonly string[];
+  readCapabilities: readonly string[];
+  cancelCapabilities: readonly string[];
+  controlCapabilities: readonly string[];
+  cancel?: boolean;
+};
+
+export type TrellisAPI = {
+  rpc: Record<string, RPCDesc>;
+  operations: Record<string, OperationDesc>;
+  events: Record<string, EventDesc>;
+  feeds?: Record<string, FeedDesc>;
+  subjects: Record<string, unknown>;
+};

package/src/contract_support/schema_pointers.ts

@@ -0,0 +1,161 @@
+export type SubjectParam = `/${string}`;
+
+type JsonPrimitive = string | number | boolean | null;
+type TokenPrimitive = string | number;
+
+type IsPlainObject<T> = T extends object ? T extends JsonPrimitive ? false
+  : T extends readonly unknown[] ? false
+  : T extends Date ? false
+  : T extends Function ? false
+  : true
+  : false;
+
+type JoinPointer<Prefix extends string, Key extends string> = Prefix extends ""
+  ? `/${Key}`
+  : `${Prefix}/${Key}`;
+
+type Dec = [0, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9];
+
+type PointerPaths<
+  T,
+  Prefix extends string,
+  Depth extends number,
+> = Depth extends 0 ? never
+  : IsPlainObject<T> extends true ? {
+      [K in Extract<keyof T, string>]-?:
+        | JoinPointer<Prefix, K>
+        | PointerPaths<NonNullable<T[K]>, JoinPointer<Prefix, K>, Dec[Depth]>;
+    }[Extract<keyof T, string>]
+  : never;
+
+export type JsonPointer<T> = PointerPaths<T, "", 6> extends infer P
+  ? P extends SubjectParam ? P
+  : never
+  : never;
+
+type ScalarPointerPaths<
+  T,
+  Prefix extends string,
+  Depth extends number,
+> = Depth extends 0 ? never
+  : IsPlainObject<T> extends true ? {
+      [K in Extract<keyof T, string>]-?: NonNullable<T[K]> extends
+        TokenPrimitive ? JoinPointer<Prefix, K>
+        : ScalarPointerPaths<
+          NonNullable<T[K]>,
+          JoinPointer<Prefix, K>,
+          Dec[Depth]
+        >;
+    }[Extract<keyof T, string>]
+  : never;
+
+export type ScalarJsonPointer<T> = ScalarPointerPaths<T, "", 6> extends infer P
+  ? P extends SubjectParam ? P
+  : never
+  : never;
+
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+
+function decodeJsonPointerSegment(segment: string): string {
+  return segment.replaceAll("~1", "/").replaceAll("~0", "~");
+}
+
+function resolveSubschema(
+  schema: unknown,
+  segments: readonly string[],
+): unknown | undefined {
+  if (segments.length === 0) return schema;
+  if (!isJsonObject(schema)) return undefined;
+
+  for (const key of ["allOf", "anyOf", "oneOf"] as const) {
+    const variants = schema[key];
+    if (!Array.isArray(variants)) continue;
+    for (const variant of variants) {
+      const resolved = resolveSubschema(variant, segments);
+      if (resolved !== undefined) return resolved;
+    }
+  }
+
+  const properties = schema.properties;
+  const [segment, ...rest] = segments;
+  if (!isJsonObject(properties) || !Object.hasOwn(properties, segment)) {
+    return undefined;
+  }
+  return resolveSubschema(properties[segment], rest);
+}
+
+function isTokenableSchema(schema: unknown): boolean {
+  if (schema === true || schema === false) return false;
+  if (!schema || typeof schema !== "object") return false;
+
+  const s = schema as Record<string, unknown>;
+
+  const allOf = s.allOf;
+  if (Array.isArray(allOf) && allOf.length > 0) {
+    return allOf.every(isTokenableSchema);
+  }
+
+  const anyOf = s.anyOf;
+  if (Array.isArray(anyOf) && anyOf.length > 0) {
+    return anyOf.every(isTokenableSchema);
+  }
+
+  const oneOf = s.oneOf;
+  if (Array.isArray(oneOf) && oneOf.length > 0) {
+    return oneOf.every(isTokenableSchema);
+  }
+
+  const constant = s.const;
+  if (typeof constant === "string" || typeof constant === "number") return true;
+
+  const enumValues = s.enum;
+  if (Array.isArray(enumValues)) {
+    if (enumValues.length === 0) return false;
+    return enumValues.every(
+      (v) => typeof v === "string" || typeof v === "number",
+    );
+  }
+
+  const type = s.type;
+  if (type === "string" || type === "number" || type === "integer") return true;
+  if (Array.isArray(type)) {
+    return type.every(
+      (t) => t === "string" || t === "number" || t === "integer",
+    );
+  }
+
+  return false;
+}
+
+export function getSubschemaAtDataPointer(
+  schema: unknown,
+  pointer: string,
+): unknown | undefined {
+  return resolveSubschema(
+    schema,
+    pointer.slice(1).split("/").map(decodeJsonPointerSegment),
+  );
+}
+
+export function assertDataPointersExistAndAreTokenable(
+  name: string,
+  schema: unknown,
+  pointers: readonly string[],
+): void {
+  for (const pointer of pointers) {
+    const node = getSubschemaAtDataPointer(schema, pointer);
+    if (node === undefined) {
+      throw new Error(
+        `Invalid event subject param pointer '${pointer}' for event '${name}' (path not found in schema)`,
+      );
+    }
+
+    if (!isTokenableSchema(node)) {
+      throw new Error(
+        `Invalid event subject param pointer '${pointer}' for event '${name}' (must resolve to string/number schema)`,
+      );
+    }
+  }
+}

package/src/contracts.ts

@@ -0,0 +1,9 @@
+import "./_dnt.polyfills.js";
+export * from "./contract_support/mod.js";
+export {
+  defineAgentContract,
+  defineAppContract,
+  defineDeviceContract,
+  defineServiceContract,
+} from "./contract.js";
+export type { DefinedContract } from "./contract.js";