Custom host

import { createFramework } from "@aventara/core";
import { AvProtocol } from "@aventara/core/protocol";

const framework = await createFramework(config);
const protocol = AvProtocol.bind(framework);

{
  method: string;
  path: string;          // relative to the `api` mount path, e.g. "/_contract"
  query?: string;        // the URL's query without its "?", as received; read only by a cached read's GET
  headers: Record<string, string | readonly string[] | undefined>;   // Node's req.headers fits
  body: { kind: "raw"; content: string | Uint8Array }   // the protocol checks size, type and JSON
      | { kind: "parsed"; value: unknown };             // your parser already did
}

// src/custom/framework.ts
import { createFramework } from "@aventara/core";
import { createPrismaAdapter } from "@aventara/prisma7-adapter";
import adapter from "../aventara.adapter.js";
import { aventaraConfig } from "../aventara.config.js";
import { PrismaService } from "../prisma.service.js";

export async function buildFramework() {
  const prisma = new PrismaService();
  return createFramework({
    ...aventaraConfig,
    adapter: await createPrismaAdapter({ ...adapter, client: prisma }),
  });
}

// src/custom/express.host.ts
import express, { type Request, type Response } from "express";
import { AvProtocol, type AvProtocolRequest, type AvProtocolResponse } from "@aventara/core/protocol";
import { buildFramework } from "./framework.js";

const framework = await buildFramework();
const protocol = AvProtocol.bind(framework);   // bind once, at startup
const base = framework.api;             // "/api"

const toRequest = (req: Request, path: string): AvProtocolRequest => ({
  method: req.method,
  path,                                        // relative to the `api` mount path
  query: req.originalUrl.split("?")[1] ?? "",  // a cached read's arguments travel here
  headers: req.headers,
  body: { kind: "raw", content: Buffer.isBuffer(req.body) ? req.body : "" },
});

const send = (res: Response, r: AvProtocolResponse) => res.status(r.status).set(r.headers).send(r.body);

// Read protocol bodies raw: the protocol enforces content type and JSON itself.
const raw = express.raw({ type: () => true, limit: framework.contracts.client.limits.maxRequestBytes });

const app = express();
app.disable("x-powered-by");

for (const route of protocol.surface()) {
  const url = base + route.path;
  const rel = (req: Request) => req.path.slice(base.length);
  if (route.kind === "contract") {
    app.get(url, (req, res) => send(res, protocol.encodeContract(toRequest(req, rel(req)))));
  } else if (route.kind === "transactions") {
    app.post(url, raw, async (req, res) => send(res, await protocol.handleTransaction(toRequest(req, rel(req)))));
  } else if (route.kind === "all") {
    // One JSON body; with `Accept: application/x-ndjson`, one line per operation as it settles.
    app.post(url, raw, async (req, res) => {
      const gone = new AbortController();          // the client left: operations not yet started never start
      res.on("close", () => gone.abort());
      const { status, headers, body } = await protocol.handleAll(toRequest(req, rel(req)), { signal: gone.signal });
      res.status(status).set(headers);
      if (typeof body === "string") return res.send(body);
      res.flushHeaders();
      for await (const line of body) res.write(line);
      res.end();
    });
  } else if (route.method === "GET") {
    // A read with a `cache` stage: also served as a GET, its arguments in the query.
    app.get(url, async (req, res) => send(res, await protocol.handleOperation(toRequest(req, rel(req)))));
  } else {
    app.post(url, raw, async (req, res) => send(res, await protocol.handleOperation(toRequest(req, rel(req)))));
  }
}

// Anything else under <api>/_* gets the protocol's own answer (404, 405 + Allow, ...).
app.use(base, (req, res, next) => {
  const answer = protocol.answerAbsent(toRequest(req, req.path));   // req.path is already relative here
  if (answer === undefined) return next();
  send(res, answer);
});

// A body over the limit is refused by the raw parser before the protocol sees it: answer in the protocol's words.
app.use((err: { type?: string }, req: Request, res: Response, next: express.NextFunction) => {
  if (err.type === "entity.too.large") return send(res, protocol.failure("A2010"));
  next(err);
});

// Your own routes live outside the protocol's "_" namespace.
app.get(`${base}/health`, (_req, res) => res.json({ ok: true }));

app.listen(Number(process.env.PORT ?? 3000), () => console.log(`listening, ${protocol.surface().length} routes`));

POST /api/_resources/Post/find/count   -> 200 {"data":4,"code":"A1000","cause":null}
transaction (Category + Post with $ref) -> committed, [ { id: 3 }, { id: 5 } ]
write without Authorization             -> AvAuthError A4000 (the pipeline guard ran)
GET  /api/health                        -> 200
DELETE /api/_contract                   -> 405, Allow: GET, code A2012
POST body of 1.1 MB                     -> 413, code A2010

// src/custom/node.host.ts
import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
import { AvProtocol, type AvProtocolResponse } from "@aventara/core/protocol";
import { buildFramework } from "./framework.js";

const framework = await buildFramework();
const protocol = AvProtocol.bind(framework);
const base = framework.api;
const maxBytes = framework.contracts.client.limits.maxRequestBytes;

// "POST /_resources/User/find/many" -> "operation", "GET /_contract" -> "contract", ...
// A read with a `cache` stage also has "GET /_resources/<R>/find/<variant>" -> "operation".
const routes = new Map<string, string>(protocol.surface().map((r) => [`${r.method} ${r.path}`, r.kind]));

const send = (res: ServerResponse, r: AvProtocolResponse) => {
  res.writeHead(r.status, r.headers);
  res.end(r.body);
};

// Collect the body, but stop once it is over the limit: the protocol then answers 413 itself.
async function readBody(req: IncomingMessage): Promise<Buffer> {
  const chunks: Buffer[] = [];
  let size = 0;
  for await (const chunk of req as AsyncIterable<Buffer>) {
    size += chunk.length;
    chunks.push(chunk);
    if (size > maxBytes) break;
  }
  return Buffer.concat(chunks);
}

createServer(async (req, res) => {
  const url = new URL(req.url ?? "/", "http://localhost");
  if (url.pathname === `${base}/health`) {
    res.writeHead(200, { "content-type": "application/json" }).end('{"ok":true}');
    return;
  }
  if (url.pathname !== base && !url.pathname.startsWith(`${base}/`)) {
    res.writeHead(404).end();
    return;
  }
  const path = url.pathname.slice(base.length);   // relative to the `api` mount path
  const request = {
    method: req.method ?? "GET",
    path,
    query: url.search.slice(1),                   // a cached read's arguments travel here
    headers: req.headers,
    body: { kind: "raw", content: req.method === "POST" ? await readBody(req) : "" },
  } as const;

  switch (routes.get(`${request.method} ${path}`)) {
    case "contract":
      return send(res, protocol.encodeContract(request));
    case "transactions":
      return send(res, await protocol.handleTransaction(request));
    case "operation":
      return send(res, await protocol.handleOperation(request));
    case "all": {
      // One JSON body; with `Accept: application/x-ndjson`, one line per operation as it settles.
      const gone = new AbortController();          // the client left: operations not yet started never start
      res.on("close", () => gone.abort());
      const { status, headers, body } = await protocol.handleAll(request, { signal: gone.signal });
      res.writeHead(status, headers);
      if (typeof body === "string") return void res.end(body);
      res.flushHeaders();
      for await (const line of body) res.write(line);
      return void res.end();
    }
    default: {
      // Not a route we mount: the protocol answers its own "_" namespace; the rest is ours.
      const answer = protocol.answerAbsent(request);
      if (answer) return send(res, answer);
      res.writeHead(404).end();
    }
  }
}).listen(Number(process.env.PORT ?? 3000), () => console.log("listening"));

{ kind: "operation", code: "A3000", origin: "client", resource: "Post", family: "find", variant: "many",
  error: AvUnmountedRouteError: The ClientContract advertises Post.find.many, but the host mounted no route for
         POST /_resources/Post/find/many, so protocol.answerAbsent answered it 500 A3000. Mount every protocol.surface() entry. }