@nyte-ai/host 0.0.0-stage → 0.0.19

package/src/serve/handler.ts

@@ -0,0 +1,362 @@
+import { Type } from "typebox";
+import { compile, isJsonObject, OPERATIONS, SdkError } from "@nyte-ai/schema";
+import type { Authority, Json } from "@nyte-ai/schema";
+import type { Connection } from "@nyte-ai/core";
+import { bindConnection } from "./binding.ts";
+import type {
+  Binding,
+  BindingOptions,
+  BindingRequest,
+  ByteBinding,
+  CallBinding,
+  FrameBinding,
+} from "./binding.ts";
+import {
+  CANCEL_PATH,
+  CHANNEL_HEADER,
+  CHANNEL_PATH,
+  HOST_HEADER,
+  INPUT_HEADER,
+  STREAM_HEADER,
+  abortable,
+  answersBytes,
+  answersOnce,
+  asSdkError,
+  decodeInput,
+  encodeError,
+  encodeOutput,
+  errorStatus,
+  mapped,
+  namesOperation,
+  octetStream,
+  outputFrames,
+  parseJson,
+  readInputHeader,
+  sseFrames,
+} from "@nyte-ai/protocol";
+import type { ByteName, CallName, FrameName, OperationName } from "@nyte-ai/protocol";
+import { createStreamChannels } from "./stream-server.ts";
+
+/** Describes the handler: how a request authenticates to a connection (with the headers its answer carries, such as a pairing's `X-Nyte-Credential`, §40j), what the binding needs, the body limit and the allowed origins. */
+export type HandlerOptions = BindingOptions & {
+  connection(request: Request): Promise<{
+    readonly connection: Connection;
+    readonly authority: ReadonlySet<Authority>;
+    readonly headers?: Readonly<Record<string, string>>;
+  }>;
+  readonly maxBodyBytes?: number;
+  readonly origins?: readonly string[];
+};
+
+const MAX_BODY_BYTES = 8 * 1024 * 1024;
+
+const UPLOADS: ReadonlySet<string> = new Set([
+  "files.write",
+  "job.write",
+  "files.upload",
+] satisfies readonly CallName[]);
+
+const ALLOWED_HEADERS = `Authorization, Content-Type, ${INPUT_HEADER}, ${CHANNEL_HEADER}, ${STREAM_HEADER}`;
+
+const EXPOSED_HEADERS = `X-Nyte-Version, X-Nyte-Mime, X-Nyte-Credential, ${HOST_HEADER}, ${CHANNEL_HEADER}`;
+
+const tooLarge = new WeakSet<SdkError>();
+
+const cancellations = compile(Type.Object({ channel: Type.String(), stream: Type.String() }));
+
+/** Returns the whole protocol as one fetch handler: `POST /<name>` per row (anything else `unknown`), CORS for `origins`, the row's authority over the connection the request authenticates to, and the body limit (413). Calls answer JSON, watches and JSON streams server-sent events, byte rows an octet stream and `job.output` framed octets (§40h, §40w); the request's abort ends every stream. An error answers its encoded `SdkError` at the status `errorStatus` gives its code. */
+export function createHandler(options: HandlerOptions): (request: Request) => Promise<Response> {
+  const limit = options.maxBodyBytes ?? MAX_BODY_BYTES;
+  const bindings = new WeakMap<Connection, Binding>();
+  const channels = createStreamChannels();
+
+  const bind = (connection: Connection): Binding => {
+    const known = bindings.get(connection);
+
+    if (known !== undefined) return known;
+    const created = bindConnection(connection, options);
+    bindings.set(connection, created);
+
+    return created;
+  };
+
+  return async (request) => {
+    const cors = corsHeaders(request, options.origins);
+
+    if (cors === null)
+      return errorResponse(new SdkError("denied", "This origin may not call the host."), {});
+
+    if (request.method === "OPTIONS")
+      return new Response(null, {
+        status: 204,
+        headers: {
+          ...cors,
+          "Access-Control-Allow-Methods": "POST",
+          "Access-Control-Allow-Headers": ALLOWED_HEADERS,
+          "Access-Control-Max-Age": "600",
+        },
+      });
+
+    try {
+      const path = new URL(request.url).pathname.slice(1);
+
+      const name =
+        request.method === "POST" && (path === CHANNEL_PATH || path === CANCEL_PATH)
+          ? path
+          : readOperation(request);
+
+      const authenticated = await options.connection(request);
+
+      if (name === CHANNEL_PATH) {
+        const value = await readBody(request, limit);
+        const deflate = isJsonObject(value) && value.deflate === true;
+
+        return withHeaders(channels.open(authenticated.connection, request.signal, deflate), {
+          ...cors,
+          ...authenticated.headers,
+        });
+      }
+
+      if (name === CANCEL_PATH) {
+        const value = await readBody(request, limit);
+
+        if (!cancellations.Check(value))
+          throw new SdkError("invalid", "A stream cancellation needs its channel and stream.");
+        channels.cancel(authenticated.connection, value.channel, value.stream);
+
+        return withHeaders(new Response(null, { status: 204 }), {
+          ...cors,
+          ...authenticated.headers,
+        });
+      }
+
+      const needed = OPERATIONS[name].authority;
+
+      if (!authenticated.authority.has(needed))
+        throw new SdkError("denied", `${name} needs ${needed} authority.`);
+      const binding = bind(authenticated.connection);
+      let response: Response;
+      const channel = request.headers.get(CHANNEL_HEADER);
+      const stream = request.headers.get(STREAM_HEADER);
+
+      if (channel !== null || stream !== null) {
+        if (channel === null || stream === null)
+          throw new SdkError("invalid", "A shared stream needs its channel and identifier.");
+        const value = await readBody(request, limit);
+
+        response = await channels.start(
+          authenticated.connection,
+          channel,
+          stream,
+          request.signal,
+          (signal) => answer(binding, name, value, request, signal),
+        );
+      } else response = await serve(binding, name, request, limit);
+
+      return withHeaders(response, { ...cors, ...authenticated.headers });
+    } catch (error) {
+      return errorResponse(asSdkError(error), cors);
+    }
+  };
+}
+
+async function serve(
+  binding: Binding,
+  name: OperationName,
+  request: Request,
+  limit: number,
+): Promise<Response> {
+  if (UPLOADS.has(name) && answersOnce(name)) {
+    const body = limited(request, limit);
+
+    return json(
+      await call(binding, name, readInputHeader(request) ?? {}, { body, signal: request.signal }),
+    );
+  }
+
+  return answer(binding, name, await readBody(request, limit), request, request.signal);
+}
+
+/** Answers `name` with its input `value`, already read from `request`: a shared stream's exchange ends with its 202, after which the request's body can no longer be read. */
+async function answer(
+  binding: Binding,
+  name: OperationName,
+  value: Json,
+  request: Request,
+  signal: AbortSignal,
+): Promise<Response> {
+  const context: BindingRequest = { body: null, signal };
+
+  if (answersOnce(name)) return json(await call(binding, name, value, context));
+
+  if (name === "job.output")
+    return new Response(
+      outputFrames(
+        abortable(await binding["job.output"](decodeInput(name, value), context), signal),
+      ),
+      { status: 200, headers: { "Content-Type": "application/octet-stream" } },
+    );
+
+  if (answersBytes(name))
+    return octetStream(await bytes(binding, name, value, context), request.signal);
+
+  return new Response(sseFrames(ending(await frames(binding, name, value, context), signal)), {
+    status: 200,
+    headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache" },
+  });
+}
+
+async function call<N extends CallName>(
+  binding: CallBinding,
+  name: N,
+  value: Json,
+  request: BindingRequest,
+): Promise<Json> {
+  return encodeOutput(name, await binding[name](decodeInput(name, value), request));
+}
+
+async function bytes<N extends ByteName>(
+  binding: ByteBinding,
+  name: N,
+  value: Json,
+  request: BindingRequest,
+) {
+  return binding[name](decodeInput(name, value), request);
+}
+
+async function frames<N extends FrameName>(
+  binding: FrameBinding,
+  name: N,
+  value: Json,
+  request: BindingRequest,
+): Promise<AsyncIterable<Json>> {
+  return mapped(await binding[name](decodeInput(name, value), request), (frame) =>
+    encodeOutput(name, frame),
+  );
+}
+
+function ending<T>(source: AsyncIterable<T>, signal: AbortSignal): AsyncIterable<T> {
+  return {
+    [Symbol.asyncIterator]() {
+      const iterator = abortable(source, signal)[Symbol.asyncIterator]();
+
+      return {
+        async next() {
+          const next = await iterator.next();
+
+          if (next.done === true && signal.reason instanceof SdkError) throw signal.reason;
+
+          return next;
+        },
+        async return() {
+          await iterator.return?.();
+
+          return { done: true, value: undefined };
+        },
+      };
+    },
+  };
+}
+
+async function readBody(request: Request, limit: number): Promise<Json> {
+  const stream = limited(request, limit);
+
+  if (stream === null) return {};
+  const chunks: Uint8Array[] = [];
+  const reader = stream.getReader();
+
+  for (;;) {
+    const read = await reader.read();
+
+    if (read.done) break;
+    chunks.push(read.value);
+  }
+
+  const decoder = new TextDecoder();
+
+  const text =
+    chunks.map((chunk) => decoder.decode(chunk, { stream: true })).join("") + decoder.decode();
+
+  return text.trim() === "" ? {} : parseJson(text);
+}
+
+function limited(request: Request, limit: number): ReadableStream<Uint8Array> | null {
+  const declared = Number(request.headers.get("Content-Length") ?? "0");
+
+  if (declared > limit) throw largerThan(limit);
+
+  if (request.body === null) return null;
+  let total = 0;
+
+  return request.body.pipeThrough(
+    new TransformStream<Uint8Array, Uint8Array>({
+      transform(chunk, controller) {
+        total += chunk.byteLength;
+
+        if (total > limit) controller.error(largerThan(limit));
+        else controller.enqueue(chunk);
+      },
+    }),
+    { signal: request.signal },
+  );
+}
+
+function largerThan(limit: number): SdkError {
+  const error = new SdkError("invalid", `The body is larger than ${limit} bytes.`);
+  tooLarge.add(error);
+
+  return error;
+}
+
+function corsHeaders(
+  request: Request,
+  origins: readonly string[] | undefined,
+): Readonly<Record<string, string>> | null {
+  const origin = request.headers.get("Origin");
+
+  if (origin === null || origin === new URL(request.url).origin) return {};
+
+  if (!(origins ?? []).includes(origin)) return null;
+
+  return {
+    "Access-Control-Allow-Origin": origin,
+    "Access-Control-Expose-Headers": EXPOSED_HEADERS,
+    Vary: "Origin",
+  };
+}
+
+function readOperation(request: Request): OperationName {
+  const path = new URL(request.url).pathname;
+  const name = path.slice(1);
+
+  if (request.method !== "POST" || !namesOperation(name))
+    throw new SdkError("unknown", `No operation answers ${request.method} ${path}.`);
+
+  return name;
+}
+
+function json(value: Json): Response {
+  return new Response(JSON.stringify(value), {
+    status: 200,
+    headers: { "Content-Type": "application/json" },
+  });
+}
+
+function errorResponse(failure: SdkError, headers: Readonly<Record<string, string>>): Response {
+  return new Response(JSON.stringify(encodeError(failure)), {
+    status: tooLarge.has(failure) ? 413 : errorStatus[failure.code],
+    headers: { ...headers, "Content-Type": "application/json" },
+  });
+}
+
+function withHeaders(response: Response, headers: Readonly<Record<string, string>>): Response {
+  const merged = new Headers(response.headers);
+
+  for (const [key, value] of Object.entries(headers)) merged.set(key, value);
+
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers: merged,
+  });
+}

package/src/serve/stream-server.ts

@@ -0,0 +1,176 @@
+import { deflateSync } from "fflate";
+import { SdkError } from "@nyte-ai/schema";
+import type { Connection } from "@nyte-ai/core";
+import { CHANNEL_HEADER, asSdkError, encodeError, streamBuffer } from "@nyte-ai/protocol";
+import type { StreamFrame } from "@nyte-ai/protocol";
+
+const encoder = new TextEncoder();
+
+const CHUNK_BYTES = 48 * 1024;
+
+/** Smaller chunks compress under ~4x and save too few bytes to pay for deflating and inflating them. */
+const DEFLATE_MIN_BYTES = 16 * 1024;
+
+export function createStreamChannels() {
+  type Channel = {
+    readonly connection: Connection;
+    readonly signal: AbortSignal;
+    readonly deflate: boolean;
+    readonly streams: Map<string, AbortController>;
+    readonly push: (frame: StreamFrame, signal: AbortSignal) => Promise<void>;
+  };
+
+  const channels = new Map<string, Channel>();
+
+  const owned = (id: string, connection: Connection): Channel => {
+    const channel = channels.get(id);
+
+    if (channel === undefined) throw new SdkError("unavailable", "The stream channel is closed.");
+
+    if (channel.connection !== connection)
+      throw new SdkError("denied", "The stream channel belongs to another connection.");
+
+    return channel;
+  };
+
+  return {
+    open(connection: Connection, signal: AbortSignal, deflate: boolean): Response {
+      const id = crypto.randomUUID();
+      const controller = new AbortController();
+      const streams = new Map<string, AbortController>();
+      let timer: ReturnType<typeof setInterval> | undefined;
+
+      const finish = (): void => {
+        if (controller.signal.aborted) return;
+        controller.abort();
+        channels.delete(id);
+        clearInterval(timer);
+        signal.removeEventListener("abort", aborted);
+
+        for (const stream of streams.values()) stream.abort();
+        streams.clear();
+      };
+
+      const buffer = streamBuffer(finish);
+
+      const fail = (error: SdkError): void => {
+        if (controller.signal.aborted) return;
+        buffer.end(encoder.encode(`event: error\ndata: ${JSON.stringify(encodeError(error))}\n\n`));
+        finish();
+      };
+
+      const aborted = (): void => {
+        fail(
+          signal.reason instanceof SdkError
+            ? signal.reason
+            : new SdkError("unavailable", "The stream channel disconnected."),
+        );
+      };
+
+      channels.set(id, {
+        connection,
+        signal: controller.signal,
+        deflate,
+        streams,
+        push: (frame, signal) =>
+          buffer.write(encoder.encode(`data: ${JSON.stringify(frame)}\n\n`), signal),
+      });
+      buffer.push(encoder.encode(": connected\n\n"));
+      timer = setInterval(() => {
+        buffer.push(encoder.encode(": ping\n\n"));
+      }, 15_000);
+
+      if (signal.aborted) aborted();
+      else signal.addEventListener("abort", aborted, { once: true });
+
+      return new Response(buffer.body, {
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          [CHANNEL_HEADER]: id,
+        },
+      });
+    },
+    async start(
+      connection: Connection,
+      channelId: string,
+      streamId: string,
+      request: AbortSignal,
+      serve: (signal: AbortSignal) => Promise<Response>,
+    ): Promise<Response> {
+      const channel = owned(channelId, connection);
+
+      if (channel.streams.has(streamId))
+        throw new SdkError("invalid", "The stream identifier is already in use.");
+      const controller = new AbortController();
+      channel.streams.set(streamId, controller);
+      const abortSetup = (): void => controller.abort(request.reason);
+      request.addEventListener("abort", abortSetup, { once: true });
+      const signal = AbortSignal.any([controller.signal, channel.signal]);
+      void (async () => {
+        let reader: Pick<ReadableStreamDefaultReader<Uint8Array>, "read" | "cancel"> | undefined;
+
+        const cancel = (): void => {
+          void reader?.cancel().catch(() => undefined);
+        };
+
+        signal.addEventListener("abort", cancel, { once: true });
+
+        try {
+          if (request.aborted) abortSetup();
+          signal.throwIfAborted();
+          const response = await serve(signal);
+          reader = response.body?.getReader();
+          request.removeEventListener("abort", abortSetup);
+
+          if (signal.aborted) return;
+
+          if (reader !== undefined)
+            for (;;) {
+              const next = await reader.read();
+
+              if (signal.aborted || next.done) break;
+
+              for (let start = 0; start < next.value.byteLength; start += CHUNK_BYTES) {
+                if (signal.aborted) break;
+                const chunk = next.value.subarray(start, start + CHUNK_BYTES);
+                await channel.push(
+                  channel.deflate && chunk.byteLength >= DEFLATE_MIN_BYTES
+                    ? {
+                        kind: "deflated",
+                        stream: streamId,
+                        data: deflateSync(chunk, { level: 1 }).toBase64(),
+                      }
+                    : { kind: "chunk", stream: streamId, data: chunk.toBase64() },
+                  signal,
+                );
+              }
+            }
+
+          if (!signal.aborted) await channel.push({ kind: "end", stream: streamId }, signal);
+        } catch (error) {
+          if (!signal.aborted)
+            await channel.push(
+              {
+                kind: "error",
+                stream: streamId,
+                error: JSON.stringify(encodeError(asSdkError(error))),
+              },
+              signal,
+            );
+        } finally {
+          request.removeEventListener("abort", abortSetup);
+          signal.removeEventListener("abort", cancel);
+          channel.streams.delete(streamId);
+          controller.abort();
+          cancel();
+        }
+      })();
+
+      return new Response(null, { status: 202 });
+    },
+    cancel(connection: Connection, channelId: string, streamId: string): void {
+      owned(channelId, connection).streams.get(streamId)?.abort();
+    },
+  };
+}

package/src/session-index.ts

@@ -0,0 +1,99 @@
+import { projectSessionIndex, sessionIndexRef } from "@nyte-ai/core/store";
+import type { SessionIndex } from "@nyte-ai/core";
+import { asId } from "@nyte-ai/schema";
+import type { Json, Revision } from "@nyte-ai/schema";
+import { parseRef, parseText } from "./store-rows.ts";
+
+type Binding = string | number | null;
+
+interface Statement {
+  readonly text: string;
+  readonly values: readonly Binding[];
+}
+
+export function sessionIndexChanges(
+  name: string,
+  object: Json | null,
+  revision: Revision,
+): readonly Statement[] {
+  const ref = sessionIndexRef(name);
+
+  if (ref === null) return [];
+  const entry = projectSessionIndex(name, object);
+
+  if (ref.kind === "session") {
+    return entry?.kind === "session"
+      ? [
+          {
+            text: "INSERT INTO session_index (name, session, parent, sort_at, version) VALUES (?, ?, ?, ?, ?) ON CONFLICT (name) DO UPDATE SET session = excluded.session, parent = excluded.parent, sort_at = excluded.sort_at, version = excluded.version",
+            values: [name, entry.session, entry.parent, -entry.at, revision],
+          },
+        ]
+      : [{ text: "DELETE FROM session_index WHERE name = ?", values: [name] }];
+  }
+
+  return entry !== null && entry.kind !== "session"
+    ? [
+        {
+          text: "INSERT INTO pending_work (name, session, kind) VALUES (?, ?, ?) ON CONFLICT (name) DO UPDATE SET session = excluded.session, kind = excluded.kind",
+          values: [name, entry.session, entry.kind],
+        },
+      ]
+    : [{ text: "DELETE FROM pending_work WHERE name = ?", values: [name] }];
+}
+
+export function sqlSessionIndex(
+  read: (text: string, values: readonly Binding[]) => Promise<readonly Record<string, unknown>[]>,
+): SessionIndex {
+  return {
+    async list({ parents, after, limit }) {
+      const conditions: string[] = [];
+      const values: Binding[] = [];
+
+      if (parents.kind === "roots") conditions.push("s.parent IS NULL");
+      if (parents.kind === "children") {
+        conditions.push("s.parent = ?");
+        values.push(parents.session);
+      }
+      if (after !== undefined) {
+        conditions.push("(s.sort_at, s.session) > (?, ?)");
+        values.push(-after.at, after.id);
+      }
+      values.push(limit);
+
+      return (
+        await read(
+          `SELECT r.name, r.target, r.revision, s.version FROM session_index s JOIN refs r ON r.name = s.name${conditions.length === 0 ? "" : ` WHERE ${conditions.join(" AND ")}`} ORDER BY s.sort_at, s.session LIMIT ?`,
+          values,
+        )
+      ).map((row) => ({
+        ref: parseRef(row),
+        version: asId<"revision">(parseText(row.version) ?? ""),
+      }));
+    },
+    async work({ after, limit }) {
+      return (
+        await read(
+          `SELECT r.name, r.target, r.revision FROM (SELECT DISTINCT session FROM pending_work${after === undefined ? "" : " WHERE session > ?"}) p JOIN session_index s ON s.session = p.session JOIN refs r ON r.name = s.name ORDER BY p.session LIMIT ?`,
+          after === undefined ? [limit] : [after, limit],
+        )
+      ).map(parseRef);
+    },
+    async pending({ kind, sessions }) {
+      if (sessions?.length === 0) return [];
+
+      return (
+        await read(
+          `SELECT r.name, r.target, r.revision FROM pending_work p JOIN refs r ON r.name = p.name WHERE p.kind = ?${sessions === undefined ? "" : ` AND p.session IN (${sessions.map(() => "?").join(", ")})`} ORDER BY p.name`,
+          [kind, ...(sessions ?? [])],
+        )
+      ).map(parseRef);
+    },
+  };
+}
+
+export function postgresSessionIndexQuery(text: string): string {
+  let parameter = 0;
+
+  return text.replaceAll("?", () => `$${++parameter}`);
+}