@plasius/graph-runtime-azure-functions 0.1.1 → 0.1.2

package/README.md

@@ -1,22 +1,123 @@
 # @plasius/graph-runtime-azure-functions
 
-Azure Functions runtime adapter for graph gateway read/write endpoints.
+[![npm version](https://img.shields.io/npm/v/@plasius/graph-runtime-azure-functions.svg)](https://www.npmjs.com/package/@plasius/graph-runtime-azure-functions)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/Plasius-LTD/graph-runtime-azure-functions/ci.yml?branch=main&label=build&style=flat)](https://github.com/Plasius-LTD/graph-runtime-azure-functions/actions/workflows/ci.yml)
+[![coverage](https://img.shields.io/codecov/c/github/Plasius-LTD/graph-runtime-azure-functions)](https://codecov.io/gh/Plasius-LTD/graph-runtime-azure-functions)
+[![License](https://img.shields.io/github/license/Plasius-LTD/graph-runtime-azure-functions)](./LICENSE)
+[![Code of Conduct](https://img.shields.io/badge/code%20of%20conduct-yes-blue.svg)](./CODE_OF_CONDUCT.md)
+[![Security Policy](https://img.shields.io/badge/security%20policy-yes-orange.svg)](./SECURITY.md)
+[![Changelog](https://img.shields.io/badge/changelog-md-blue.svg)](./CHANGELOG.md)
+
+[![CI](https://github.com/Plasius-LTD/graph-runtime-azure-functions/actions/workflows/ci.yml/badge.svg)](https://github.com/Plasius-LTD/graph-runtime-azure-functions/actions/workflows/ci.yml)
+[![CD](https://github.com/Plasius-LTD/graph-runtime-azure-functions/actions/workflows/cd.yml/badge.svg)](https://github.com/Plasius-LTD/graph-runtime-azure-functions/actions/workflows/cd.yml)
+
+Azure Functions runtime adapter for graph read and write HTTP handlers.
+
+Apache-2.0. ESM + CJS builds. TypeScript types included.
+
+---
+
+## Requirements
+
+- Node.js 24+ (matches `.nvmrc` and CI/CD)
+- `@azure/functions` 4.x (`peerDependencies`)
+- `@plasius/graph-gateway-core`
+- `@plasius/graph-write-coordinator`
+
+---
 
 ## Installation
 
-npm install @plasius/graph-runtime-azure-functions
+```bash
+npm install @plasius/graph-runtime-azure-functions @azure/functions
+```
+
+---
+
+## Exports
+
+```ts
+import {
+  createGraphReadHandler,
+  createGraphWriteHandler,
+  type GraphReadHandlerOptions,
+  type GraphWriteHandlerOptions,
+} from "@plasius/graph-runtime-azure-functions";
+```
+
+---
+
+## Quick Start
+
+```ts
+import { app } from "@azure/functions";
+import {
+  createGraphReadHandler,
+  createGraphWriteHandler,
+} from "@plasius/graph-runtime-azure-functions";
+
+app.http("graph-read", {
+  methods: ["POST"],
+  authLevel: "function",
+  handler: createGraphReadHandler({ gateway, telemetry }),
+});
+
+app.http("graph-write", {
+  methods: ["POST"],
+  authLevel: "function",
+  handler: createGraphWriteHandler({ coordinator, telemetry }),
+});
+```
+
+---
+
+## Security and Input Validation
+
+Handler factories enforce boundary validation for external input:
+
+- Read payloads must satisfy `isGraphQuery`.
+- Write payloads must satisfy strict write-command shape rules (idempotency/partition/aggregate keys + payload + timestamp).
+- Optional payload size guard via `maxBodyBytes` (default `64KB`, returns `413` when exceeded).
+- Optional authorization guard via `authorize(context)` (returns `403` when denied).
+
+Failure responses are bounded and sanitized:
+
+- Read validation/auth/body-limit: `400/403/413`
+- Read upstream execution failure: `502`
+- Write validation/auth/body-limit: `400/403/413`
+- Write upstream execution failure: `503`
+
+---
 
 ## Development
 
+```bash
+npm run clean
 npm install
+npm run lint
+npm run typecheck
+npm run test:coverage
 npm run build
-npm test
+```
+
+---
+
+## Telemetry
+
+Both handlers accept optional `telemetry` (`TelemetrySink`) and emit:
+
+- Read: `graph.runtime.read.request`, `graph.runtime.read.latency`, `graph.runtime.read.error`
+- Write: `graph.runtime.write.request`, `graph.runtime.write.latency`, `graph.runtime.write.error`
+
+---
 
 ## Architecture
 
-- ADR documents are in docs/adrs/.
-- Cross-package architecture is tracked in plasius-ltd-site/docs/adrs/adr-0020 through adr-0024.
+- Package ADRs: [`docs/adrs`](./docs/adrs)
+- Cross-package ADRs: `plasius-ltd-site/docs/adrs/adr-0020` to `adr-0024`
+
+---
 
 ## License
 
-Apache-2.0
+Licensed under the [Apache-2.0 License](./LICENSE).

package/dist/index.cjs

@@ -26,6 +26,40 @@ __export(index_exports, {
 module.exports = __toCommonJS(index_exports);
 
 // src/handlers.ts
+var import_graph_contracts = require("@plasius/graph-contracts");
+var DEFAULT_MAX_BODY_BYTES = 64 * 1024;
+var isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var isSafeKey = (value) => /^[A-Za-z0-9:_-]+$/.test(value);
+var isWriteCommandPayloadValid = (value) => {
+  if (!isObject(value)) {
+    return false;
+  }
+  if (typeof value.idempotencyKey !== "string" || value.idempotencyKey.length === 0 || value.idempotencyKey.length > 128 || !isSafeKey(value.idempotencyKey)) {
+    return false;
+  }
+  if (typeof value.partitionKey !== "string" || value.partitionKey.length === 0 || value.partitionKey.length > 128 || !isSafeKey(value.partitionKey)) {
+    return false;
+  }
+  if (typeof value.aggregateKey !== "string" || value.aggregateKey.length === 0 || value.aggregateKey.length > 256 || !isSafeKey(value.aggregateKey)) {
+    return false;
+  }
+  if (!isObject(value.payload)) {
+    return false;
+  }
+  if (typeof value.submittedAtEpochMs !== "number" || !Number.isFinite(value.submittedAtEpochMs) || value.submittedAtEpochMs < 0) {
+    return false;
+  }
+  return value.actorId === void 0 || typeof value.actorId === "string" && value.actorId.length > 0 && value.actorId.length <= 128;
+};
+var HandlerValidationError = class extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+};
 var jsonResponse = (status, body) => ({
   status,
   jsonBody: body,
@@ -34,34 +68,167 @@ var jsonResponse = (status, body) => ({
     "cache-control": "no-store"
   }
 });
+var getContentLength = (request) => {
+  const raw = request.headers?.get?.("content-length");
+  if (!raw) {
+    return null;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return null;
+  }
+  return parsed;
+};
+var enforceBodyLimit = (request, maxBodyBytes) => {
+  const contentLength = getContentLength(request);
+  if (contentLength !== null && contentLength > maxBodyBytes) {
+    throw new HandlerValidationError(413, "GRAPH_REQUEST_BODY_TOO_LARGE", "Request payload exceeds allowed limit.");
+  }
+};
+var enforceAuthorization = async (authorize, operation, request, context) => {
+  if (!authorize) {
+    return;
+  }
+  const allowed = await authorize({ operation, request, context });
+  if (!allowed) {
+    throw new HandlerValidationError(403, "GRAPH_FORBIDDEN", "Forbidden");
+  }
+};
 var createGraphReadHandler = (options) => {
   return async (request, context) => {
+    const startedAt = Date.now();
+    options.telemetry?.metric({
+      name: "graph.runtime.read.request",
+      value: 1,
+      unit: "count"
+    });
     try {
-      const query = await request.json();
+      const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+      enforceBodyLimit(request, maxBodyBytes);
+      await enforceAuthorization(options.authorize, "read", request, context);
+      let rawBody;
+      try {
+        rawBody = await request.json();
+      } catch {
+        throw new HandlerValidationError(400, "GRAPH_READ_REQUEST_INVALID", "Invalid graph read request.");
+      }
+      if (!(0, import_graph_contracts.isGraphQuery)(rawBody)) {
+        throw new HandlerValidationError(400, "GRAPH_READ_REQUEST_INVALID", "Invalid graph read request.");
+      }
+      const query = rawBody;
       const result = await options.gateway.execute({
         ...query,
         traceId: query.traceId ?? context.traceContext?.traceParent
       });
+      options.telemetry?.metric({
+        name: "graph.runtime.read.latency",
+        value: Date.now() - startedAt,
+        unit: "ms",
+        tags: { status: "200" }
+      });
       return jsonResponse(200, result);
     } catch (error) {
-      return jsonResponse(400, {
-        code: "GRAPH_READ_REQUEST_INVALID",
-        message: error instanceof Error ? error.message : "Invalid read request"
+      if (error instanceof HandlerValidationError) {
+        options.telemetry?.metric({
+          name: "graph.runtime.read.error",
+          value: 1,
+          unit: "count",
+          tags: { code: error.code }
+        });
+        options.telemetry?.error({
+          message: error.message,
+          source: "graph-runtime-azure-functions.read",
+          code: error.code
+        });
+        return jsonResponse(error.status, {
+          code: error.code,
+          message: error.message
+        });
+      }
+      options.telemetry?.metric({
+        name: "graph.runtime.read.error",
+        value: 1,
+        unit: "count",
+        tags: { code: "GRAPH_READ_UPSTREAM_FAILED" }
+      });
+      options.telemetry?.error({
+        message: "Graph read failed",
+        source: "graph-runtime-azure-functions.read",
+        code: "GRAPH_READ_UPSTREAM_FAILED"
+      });
+      return jsonResponse(502, {
+        code: "GRAPH_READ_UPSTREAM_FAILED",
+        message: "Graph read failed."
       });
     }
   };
 };
 var createGraphWriteHandler = (options) => {
-  return async (request) => {
+  return async (request, context) => {
+    const startedAt = Date.now();
+    options.telemetry?.metric({
+      name: "graph.runtime.write.request",
+      value: 1,
+      unit: "count"
+    });
     try {
-      const command = await request.json();
+      const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+      enforceBodyLimit(request, maxBodyBytes);
+      await enforceAuthorization(options.authorize, "write", request, context);
+      let rawBody;
+      try {
+        rawBody = await request.json();
+      } catch {
+        throw new HandlerValidationError(400, "GRAPH_WRITE_REQUEST_INVALID", "Invalid graph write request.");
+      }
+      if (!isWriteCommandPayloadValid(rawBody)) {
+        throw new HandlerValidationError(400, "GRAPH_WRITE_REQUEST_INVALID", "Invalid graph write request.");
+      }
+      const command = rawBody;
       const operation = await options.coordinator.submit(command);
       const status = operation.state === "succeeded" ? 200 : 202;
+      options.telemetry?.metric({
+        name: "graph.runtime.write.latency",
+        value: Date.now() - startedAt,
+        unit: "ms",
+        tags: {
+          status: String(status),
+          state: operation.state
+        }
+      });
       return jsonResponse(status, operation);
     } catch (error) {
-      return jsonResponse(400, {
-        code: "GRAPH_WRITE_REQUEST_INVALID",
-        message: error instanceof Error ? error.message : "Invalid write request"
+      if (error instanceof HandlerValidationError) {
+        options.telemetry?.metric({
+          name: "graph.runtime.write.error",
+          value: 1,
+          unit: "count",
+          tags: { code: error.code }
+        });
+        options.telemetry?.error({
+          message: error.message,
+          source: "graph-runtime-azure-functions.write",
+          code: error.code
+        });
+        return jsonResponse(error.status, {
+          code: error.code,
+          message: error.message
+        });
+      }
+      options.telemetry?.metric({
+        name: "graph.runtime.write.error",
+        value: 1,
+        unit: "count",
+        tags: { code: "GRAPH_WRITE_UPSTREAM_FAILED" }
+      });
+      options.telemetry?.error({
+        message: "Graph write failed",
+        source: "graph-runtime-azure-functions.write",
+        code: "GRAPH_WRITE_UPSTREAM_FAILED"
+      });
+      return jsonResponse(503, {
+        code: "GRAPH_WRITE_UPSTREAM_FAILED",
+        message: "Graph write failed."
       });
     }
   };

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/handlers.ts"],"sourcesContent":["export * from \"./handlers.js\";\n","import type { HttpHandler, HttpRequest, HttpResponseInit, InvocationContext } from \"@azure/functions\";\nimport type { GraphQuery, WriteCommand } from \"@plasius/graph-contracts\";\nimport type { GraphGateway } from \"@plasius/graph-gateway-core\";\nimport type { WriteCoordinator } from \"@plasius/graph-write-coordinator\";\n\nexport interface GraphReadHandlerOptions {\n  gateway: Pick<GraphGateway, \"execute\">;\n}\n\nexport interface GraphWriteHandlerOptions {\n  coordinator: Pick<WriteCoordinator, \"submit\">;\n}\n\nconst jsonResponse = (status: number, body: unknown): HttpResponseInit => ({\n  status,\n  jsonBody: body,\n  headers: {\n    \"content-type\": \"application/json\",\n    \"cache-control\": \"no-store\",\n  },\n});\n\nexport const createGraphReadHandler = (options: GraphReadHandlerOptions): HttpHandler => {\n  return async (request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> => {\n    try {\n      const query = (await request.json()) as GraphQuery;\n      const result = await options.gateway.execute({\n        ...query,\n        traceId: query.traceId ?? context.traceContext?.traceParent,\n      });\n      return jsonResponse(200, result);\n    } catch (error) {\n      return jsonResponse(400, {\n        code: \"GRAPH_READ_REQUEST_INVALID\",\n        message: error instanceof Error ? error.message : \"Invalid read request\",\n      });\n    }\n  };\n};\n\nexport const createGraphWriteHandler = (options: GraphWriteHandlerOptions): HttpHandler => {\n  return async (request: HttpRequest): Promise<HttpResponseInit> => {\n    try {\n      const command = (await request.json()) as WriteCommand;\n      const operation = await options.coordinator.submit(command);\n      const status = operation.state === \"succeeded\" ? 200 : 202;\n      return jsonResponse(status, operation);\n    } catch (error) {\n      return jsonResponse(400, {\n        code: \"GRAPH_WRITE_REQUEST_INVALID\",\n        message: error instanceof Error ? error.message : \"Invalid write request\",\n      });\n    }\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACaA,IAAM,eAAe,CAAC,QAAgB,UAAqC;AAAA,EACzE;AAAA,EACA,UAAU;AAAA,EACV,SAAS;AAAA,IACP,gBAAgB;AAAA,IAChB,iBAAiB;AAAA,EACnB;AACF;AAEO,IAAM,yBAAyB,CAAC,YAAkD;AACvF,SAAO,OAAO,SAAsB,YAA0D;AAC5F,QAAI;AACF,YAAM,QAAS,MAAM,QAAQ,KAAK;AAClC,YAAM,SAAS,MAAM,QAAQ,QAAQ,QAAQ;AAAA,QAC3C,GAAG;AAAA,QACH,SAAS,MAAM,WAAW,QAAQ,cAAc;AAAA,MAClD,CAAC;AACD,aAAO,aAAa,KAAK,MAAM;AAAA,IACjC,SAAS,OAAO;AACd,aAAO,aAAa,KAAK;AAAA,QACvB,MAAM;AAAA,QACN,SAAS,iBAAiB,QAAQ,MAAM,UAAU;AAAA,MACpD,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAEO,IAAM,0BAA0B,CAAC,YAAmD;AACzF,SAAO,OAAO,YAAoD;AAChE,QAAI;AACF,YAAM,UAAW,MAAM,QAAQ,KAAK;AACpC,YAAM,YAAY,MAAM,QAAQ,YAAY,OAAO,OAAO;AAC1D,YAAM,SAAS,UAAU,UAAU,cAAc,MAAM;AACvD,aAAO,aAAa,QAAQ,SAAS;AAAA,IACvC,SAAS,OAAO;AACd,aAAO,aAAa,KAAK;AAAA,QACvB,MAAM;AAAA,QACN,SAAS,iBAAiB,QAAQ,MAAM,UAAU;AAAA,MACpD,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/handlers.ts"],"sourcesContent":["export * from \"./handlers.js\";\n","import type { HttpHandler, HttpRequest, HttpResponseInit, InvocationContext } from \"@azure/functions\";\nimport { isGraphQuery, type GraphQuery, type TelemetrySink, type WriteCommand } from \"@plasius/graph-contracts\";\nimport type { GraphGateway } from \"@plasius/graph-gateway-core\";\nimport type { WriteCoordinator } from \"@plasius/graph-write-coordinator\";\n\nexport interface HandlerAuthContext {\n  operation: \"read\" | \"write\";\n  request: HttpRequest;\n  context: InvocationContext;\n}\n\nexport type AuthorizeHandler = (context: HandlerAuthContext) => Promise<boolean> | boolean;\n\nexport interface GraphReadHandlerOptions {\n  gateway: Pick<GraphGateway, \"execute\">;\n  telemetry?: TelemetrySink;\n  authorize?: AuthorizeHandler;\n  maxBodyBytes?: number;\n}\n\nexport interface GraphWriteHandlerOptions {\n  coordinator: Pick<WriteCoordinator, \"submit\">;\n  telemetry?: TelemetrySink;\n  authorize?: AuthorizeHandler;\n  maxBodyBytes?: number;\n}\n\nconst DEFAULT_MAX_BODY_BYTES = 64 * 1024;\n\nconst isObject = (value: unknown): value is Record<string, unknown> =>\n  value !== null && typeof value === \"object\" && !Array.isArray(value);\n\nconst isSafeKey = (value: string): boolean => /^[A-Za-z0-9:_-]+$/.test(value);\n\nconst isWriteCommandPayloadValid = (value: unknown): value is WriteCommand => {\n  if (!isObject(value)) {\n    return false;\n  }\n\n  if (\n    typeof value.idempotencyKey !== \"string\"\n    || value.idempotencyKey.length === 0\n    || value.idempotencyKey.length > 128\n    || !isSafeKey(value.idempotencyKey)\n  ) {\n    return false;\n  }\n\n  if (\n    typeof value.partitionKey !== \"string\"\n    || value.partitionKey.length === 0\n    || value.partitionKey.length > 128\n    || !isSafeKey(value.partitionKey)\n  ) {\n    return false;\n  }\n\n  if (\n    typeof value.aggregateKey !== \"string\"\n    || value.aggregateKey.length === 0\n    || value.aggregateKey.length > 256\n    || !isSafeKey(value.aggregateKey)\n  ) {\n    return false;\n  }\n\n  if (!isObject(value.payload)) {\n    return false;\n  }\n\n  if (typeof value.submittedAtEpochMs !== \"number\" || !Number.isFinite(value.submittedAtEpochMs) || value.submittedAtEpochMs < 0) {\n    return false;\n  }\n\n  return value.actorId === undefined || (typeof value.actorId === \"string\" && value.actorId.length > 0 && value.actorId.length <= 128);\n};\n\nclass HandlerValidationError extends Error {\n  public readonly status: number;\n  public readonly code: string;\n\n  public constructor(status: number, code: string, message: string) {\n    super(message);\n    this.status = status;\n    this.code = code;\n  }\n}\n\nconst jsonResponse = (status: number, body: unknown): HttpResponseInit => ({\n  status,\n  jsonBody: body,\n  headers: {\n    \"content-type\": \"application/json\",\n    \"cache-control\": \"no-store\",\n  },\n});\n\nconst getContentLength = (request: HttpRequest): number | null => {\n  const raw = request.headers?.get?.(\"content-length\");\n  if (!raw) {\n    return null;\n  }\n\n  const parsed = Number.parseInt(raw, 10);\n  if (!Number.isFinite(parsed) || parsed < 0) {\n    return null;\n  }\n\n  return parsed;\n};\n\nconst enforceBodyLimit = (request: HttpRequest, maxBodyBytes: number): void => {\n  const contentLength = getContentLength(request);\n  if (contentLength !== null && contentLength > maxBodyBytes) {\n    throw new HandlerValidationError(413, \"GRAPH_REQUEST_BODY_TOO_LARGE\", \"Request payload exceeds allowed limit.\");\n  }\n};\n\nconst enforceAuthorization = async (\n  authorize: AuthorizeHandler | undefined,\n  operation: \"read\" | \"write\",\n  request: HttpRequest,\n  context: InvocationContext,\n): Promise<void> => {\n  if (!authorize) {\n    return;\n  }\n\n  const allowed = await authorize({ operation, request, context });\n  if (!allowed) {\n    throw new HandlerValidationError(403, \"GRAPH_FORBIDDEN\", \"Forbidden\");\n  }\n};\n\nexport const createGraphReadHandler = (options: GraphReadHandlerOptions): HttpHandler => {\n  return async (request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> => {\n    const startedAt = Date.now();\n    options.telemetry?.metric({\n      name: \"graph.runtime.read.request\",\n      value: 1,\n      unit: \"count\",\n    });\n    try {\n      const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;\n      enforceBodyLimit(request, maxBodyBytes);\n      await enforceAuthorization(options.authorize, \"read\", request, context);\n\n      let rawBody: unknown;\n      try {\n        rawBody = await request.json();\n      } catch {\n        throw new HandlerValidationError(400, \"GRAPH_READ_REQUEST_INVALID\", \"Invalid graph read request.\");\n      }\n      if (!isGraphQuery(rawBody)) {\n        throw new HandlerValidationError(400, \"GRAPH_READ_REQUEST_INVALID\", \"Invalid graph read request.\");\n      }\n\n      const query = rawBody as GraphQuery;\n      const result = await options.gateway.execute({\n        ...query,\n        traceId: query.traceId ?? context.traceContext?.traceParent,\n      });\n      options.telemetry?.metric({\n        name: \"graph.runtime.read.latency\",\n        value: Date.now() - startedAt,\n        unit: \"ms\",\n        tags: { status: \"200\" },\n      });\n      return jsonResponse(200, result);\n    } catch (error) {\n      if (error instanceof HandlerValidationError) {\n        options.telemetry?.metric({\n          name: \"graph.runtime.read.error\",\n          value: 1,\n          unit: \"count\",\n          tags: { code: error.code },\n        });\n        options.telemetry?.error({\n          message: error.message,\n          source: \"graph-runtime-azure-functions.read\",\n          code: error.code,\n        });\n        return jsonResponse(error.status, {\n          code: error.code,\n          message: error.message,\n        });\n      }\n\n      options.telemetry?.metric({\n        name: \"graph.runtime.read.error\",\n        value: 1,\n        unit: \"count\",\n        tags: { code: \"GRAPH_READ_UPSTREAM_FAILED\" },\n      });\n      options.telemetry?.error({\n        message: \"Graph read failed\",\n        source: \"graph-runtime-azure-functions.read\",\n        code: \"GRAPH_READ_UPSTREAM_FAILED\",\n      });\n      return jsonResponse(502, {\n        code: \"GRAPH_READ_UPSTREAM_FAILED\",\n        message: \"Graph read failed.\",\n      });\n    }\n  };\n};\n\nexport const createGraphWriteHandler = (options: GraphWriteHandlerOptions): HttpHandler => {\n  return async (request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> => {\n    const startedAt = Date.now();\n    options.telemetry?.metric({\n      name: \"graph.runtime.write.request\",\n      value: 1,\n      unit: \"count\",\n    });\n    try {\n      const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;\n      enforceBodyLimit(request, maxBodyBytes);\n      await enforceAuthorization(options.authorize, \"write\", request, context);\n\n      let rawBody: unknown;\n      try {\n        rawBody = await request.json();\n      } catch {\n        throw new HandlerValidationError(400, \"GRAPH_WRITE_REQUEST_INVALID\", \"Invalid graph write request.\");\n      }\n      if (!isWriteCommandPayloadValid(rawBody)) {\n        throw new HandlerValidationError(400, \"GRAPH_WRITE_REQUEST_INVALID\", \"Invalid graph write request.\");\n      }\n\n      const command = rawBody as WriteCommand;\n      const operation = await options.coordinator.submit(command);\n      const status = operation.state === \"succeeded\" ? 200 : 202;\n      options.telemetry?.metric({\n        name: \"graph.runtime.write.latency\",\n        value: Date.now() - startedAt,\n        unit: \"ms\",\n        tags: {\n          status: String(status),\n          state: operation.state,\n        },\n      });\n      return jsonResponse(status, operation);\n    } catch (error) {\n      if (error instanceof HandlerValidationError) {\n        options.telemetry?.metric({\n          name: \"graph.runtime.write.error\",\n          value: 1,\n          unit: \"count\",\n          tags: { code: error.code },\n        });\n        options.telemetry?.error({\n          message: error.message,\n          source: \"graph-runtime-azure-functions.write\",\n          code: error.code,\n        });\n        return jsonResponse(error.status, {\n          code: error.code,\n          message: error.message,\n        });\n      }\n\n      options.telemetry?.metric({\n        name: \"graph.runtime.write.error\",\n        value: 1,\n        unit: \"count\",\n        tags: { code: \"GRAPH_WRITE_UPSTREAM_FAILED\" },\n      });\n      options.telemetry?.error({\n        message: \"Graph write failed\",\n        source: \"graph-runtime-azure-functions.write\",\n        code: \"GRAPH_WRITE_UPSTREAM_FAILED\",\n      });\n      return jsonResponse(503, {\n        code: \"GRAPH_WRITE_UPSTREAM_FAILED\",\n        message: \"Graph write failed.\",\n      });\n    }\n  };\n};\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACCA,6BAAqF;AA0BrF,IAAM,yBAAyB,KAAK;AAEpC,IAAM,WAAW,CAAC,UAChB,UAAU,QAAQ,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK;AAErE,IAAM,YAAY,CAAC,UAA2B,oBAAoB,KAAK,KAAK;AAE5E,IAAM,6BAA6B,CAAC,UAA0C;AAC5E,MAAI,CAAC,SAAS,KAAK,GAAG;AACpB,WAAO;AAAA,EACT;AAEA,MACE,OAAO,MAAM,mBAAmB,YAC7B,MAAM,eAAe,WAAW,KAChC,MAAM,eAAe,SAAS,OAC9B,CAAC,UAAU,MAAM,cAAc,GAClC;AACA,WAAO;AAAA,EACT;AAEA,MACE,OAAO,MAAM,iBAAiB,YAC3B,MAAM,aAAa,WAAW,KAC9B,MAAM,aAAa,SAAS,OAC5B,CAAC,UAAU,MAAM,YAAY,GAChC;AACA,WAAO;AAAA,EACT;AAEA,MACE,OAAO,MAAM,iBAAiB,YAC3B,MAAM,aAAa,WAAW,KAC9B,MAAM,aAAa,SAAS,OAC5B,CAAC,UAAU,MAAM,YAAY,GAChC;AACA,WAAO;AAAA,EACT;AAEA,MAAI,CAAC,SAAS,MAAM,OAAO,GAAG;AAC5B,WAAO;AAAA,EACT;AAEA,MAAI,OAAO,MAAM,uBAAuB,YAAY,CAAC,OAAO,SAAS,MAAM,kBAAkB,KAAK,MAAM,qBAAqB,GAAG;AAC9H,WAAO;AAAA,EACT;AAEA,SAAO,MAAM,YAAY,UAAc,OAAO,MAAM,YAAY,YAAY,MAAM,QAAQ,SAAS,KAAK,MAAM,QAAQ,UAAU;AAClI;AAEA,IAAM,yBAAN,cAAqC,MAAM;AAAA,EACzB;AAAA,EACA;AAAA,EAET,YAAY,QAAgB,MAAc,SAAiB;AAChE,UAAM,OAAO;AACb,SAAK,SAAS;AACd,SAAK,OAAO;AAAA,EACd;AACF;AAEA,IAAM,eAAe,CAAC,QAAgB,UAAqC;AAAA,EACzE;AAAA,EACA,UAAU;AAAA,EACV,SAAS;AAAA,IACP,gBAAgB;AAAA,IAChB,iBAAiB;AAAA,EACnB;AACF;AAEA,IAAM,mBAAmB,CAAC,YAAwC;AAChE,QAAM,MAAM,QAAQ,SAAS,MAAM,gBAAgB;AACnD,MAAI,CAAC,KAAK;AACR,WAAO;AAAA,EACT;AAEA,QAAM,SAAS,OAAO,SAAS,KAAK,EAAE;AACtC,MAAI,CAAC,OAAO,SAAS,MAAM,KAAK,SAAS,GAAG;AAC1C,WAAO;AAAA,EACT;AAEA,SAAO;AACT;AAEA,IAAM,mBAAmB,CAAC,SAAsB,iBAA+B;AAC7E,QAAM,gBAAgB,iBAAiB,OAAO;AAC9C,MAAI,kBAAkB,QAAQ,gBAAgB,cAAc;AAC1D,UAAM,IAAI,uBAAuB,KAAK,gCAAgC,wCAAwC;AAAA,EAChH;AACF;AAEA,IAAM,uBAAuB,OAC3B,WACA,WACA,SACA,YACkB;AAClB,MAAI,CAAC,WAAW;AACd;AAAA,EACF;AAEA,QAAM,UAAU,MAAM,UAAU,EAAE,WAAW,SAAS,QAAQ,CAAC;AAC/D,MAAI,CAAC,SAAS;AACZ,UAAM,IAAI,uBAAuB,KAAK,mBAAmB,WAAW;AAAA,EACtE;AACF;AAEO,IAAM,yBAAyB,CAAC,YAAkD;AACvF,SAAO,OAAO,SAAsB,YAA0D;AAC5F,UAAM,YAAY,KAAK,IAAI;AAC3B,YAAQ,WAAW,OAAO;AAAA,MACxB,MAAM;AAAA,MACN,OAAO;AAAA,MACP,MAAM;AAAA,IACR,CAAC;AACD,QAAI;AACF,YAAM,eAAe,QAAQ,gBAAgB;AAC7C,uBAAiB,SAAS,YAAY;AACtC,YAAM,qBAAqB,QAAQ,WAAW,QAAQ,SAAS,OAAO;AAEtE,UAAI;AACJ,UAAI;AACF,kBAAU,MAAM,QAAQ,KAAK;AAAA,MAC/B,QAAQ;AACN,cAAM,IAAI,uBAAuB,KAAK,8BAA8B,6BAA6B;AAAA,MACnG;AACA,UAAI,KAAC,qCAAa,OAAO,GAAG;AAC1B,cAAM,IAAI,uBAAuB,KAAK,8BAA8B,6BAA6B;AAAA,MACnG;AAEA,YAAM,QAAQ;AACd,YAAM,SAAS,MAAM,QAAQ,QAAQ,QAAQ;AAAA,QAC3C,GAAG;AAAA,QACH,SAAS,MAAM,WAAW,QAAQ,cAAc;AAAA,MAClD,CAAC;AACD,cAAQ,WAAW,OAAO;AAAA,QACxB,MAAM;AAAA,QACN,OAAO,KAAK,IAAI,IAAI;AAAA,QACpB,MAAM;AAAA,QACN,MAAM,EAAE,QAAQ,MAAM;AAAA,MACxB,CAAC;AACD,aAAO,aAAa,KAAK,MAAM;AAAA,IACjC,SAAS,OAAO;AACd,UAAI,iBAAiB,wBAAwB;AAC3C,gBAAQ,WAAW,OAAO;AAAA,UACxB,MAAM;AAAA,UACN,OAAO;AAAA,UACP,MAAM;AAAA,UACN,MAAM,EAAE,MAAM,MAAM,KAAK;AAAA,QAC3B,CAAC;AACD,gBAAQ,WAAW,MAAM;AAAA,UACvB,SAAS,MAAM;AAAA,UACf,QAAQ;AAAA,UACR,MAAM,MAAM;AAAA,QACd,CAAC;AACD,eAAO,aAAa,MAAM,QAAQ;AAAA,UAChC,MAAM,MAAM;AAAA,UACZ,SAAS,MAAM;AAAA,QACjB,CAAC;AAAA,MACH;AAEA,cAAQ,WAAW,OAAO;AAAA,QACxB,MAAM;AAAA,QACN,OAAO;AAAA,QACP,MAAM;AAAA,QACN,MAAM,EAAE,MAAM,6BAA6B;AAAA,MAC7C,CAAC;AACD,cAAQ,WAAW,MAAM;AAAA,QACvB,SAAS;AAAA,QACT,QAAQ;AAAA,QACR,MAAM;AAAA,MACR,CAAC;AACD,aAAO,aAAa,KAAK;AAAA,QACvB,MAAM;AAAA,QACN,SAAS;AAAA,MACX,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAEO,IAAM,0BAA0B,CAAC,YAAmD;AACzF,SAAO,OAAO,SAAsB,YAA0D;AAC5F,UAAM,YAAY,KAAK,IAAI;AAC3B,YAAQ,WAAW,OAAO;AAAA,MACxB,MAAM;AAAA,MACN,OAAO;AAAA,MACP,MAAM;AAAA,IACR,CAAC;AACD,QAAI;AACF,YAAM,eAAe,QAAQ,gBAAgB;AAC7C,uBAAiB,SAAS,YAAY;AACtC,YAAM,qBAAqB,QAAQ,WAAW,SAAS,SAAS,OAAO;AAEvE,UAAI;AACJ,UAAI;AACF,kBAAU,MAAM,QAAQ,KAAK;AAAA,MAC/B,QAAQ;AACN,cAAM,IAAI,uBAAuB,KAAK,+BAA+B,8BAA8B;AAAA,MACrG;AACA,UAAI,CAAC,2BAA2B,OAAO,GAAG;AACxC,cAAM,IAAI,uBAAuB,KAAK,+BAA+B,8BAA8B;AAAA,MACrG;AAEA,YAAM,UAAU;AAChB,YAAM,YAAY,MAAM,QAAQ,YAAY,OAAO,OAAO;AAC1D,YAAM,SAAS,UAAU,UAAU,cAAc,MAAM;AACvD,cAAQ,WAAW,OAAO;AAAA,QACxB,MAAM;AAAA,QACN,OAAO,KAAK,IAAI,IAAI;AAAA,QACpB,MAAM;AAAA,QACN,MAAM;AAAA,UACJ,QAAQ,OAAO,MAAM;AAAA,UACrB,OAAO,UAAU;AAAA,QACnB;AAAA,MACF,CAAC;AACD,aAAO,aAAa,QAAQ,SAAS;AAAA,IACvC,SAAS,OAAO;AACd,UAAI,iBAAiB,wBAAwB;AAC3C,gBAAQ,WAAW,OAAO;AAAA,UACxB,MAAM;AAAA,UACN,OAAO;AAAA,UACP,MAAM;AAAA,UACN,MAAM,EAAE,MAAM,MAAM,KAAK;AAAA,QAC3B,CAAC;AACD,gBAAQ,WAAW,MAAM;AAAA,UACvB,SAAS,MAAM;AAAA,UACf,QAAQ;AAAA,UACR,MAAM,MAAM;AAAA,QACd,CAAC;AACD,eAAO,aAAa,MAAM,QAAQ;AAAA,UAChC,MAAM,MAAM;AAAA,UACZ,SAAS,MAAM;AAAA,QACjB,CAAC;AAAA,MACH;AAEA,cAAQ,WAAW,OAAO;AAAA,QACxB,MAAM;AAAA,QACN,OAAO;AAAA,QACP,MAAM;AAAA,QACN,MAAM,EAAE,MAAM,8BAA8B;AAAA,MAC9C,CAAC;AACD,cAAQ,WAAW,MAAM;AAAA,QACvB,SAAS;AAAA,QACT,QAAQ;AAAA,QACR,MAAM;AAAA,MACR,CAAC;AACD,aAAO,aAAa,KAAK;AAAA,QACvB,MAAM;AAAA,QACN,SAAS;AAAA,MACX,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":[]}

package/dist/index.d.cts

@@ -1,14 +1,27 @@
-import { HttpHandler } from '@azure/functions';
+import { HttpRequest, InvocationContext, HttpHandler } from '@azure/functions';
+import { TelemetrySink } from '@plasius/graph-contracts';
 import { GraphGateway } from '@plasius/graph-gateway-core';
 import { WriteCoordinator } from '@plasius/graph-write-coordinator';
 
+interface HandlerAuthContext {
+    operation: "read" | "write";
+    request: HttpRequest;
+    context: InvocationContext;
+}
+type AuthorizeHandler = (context: HandlerAuthContext) => Promise<boolean> | boolean;
 interface GraphReadHandlerOptions {
     gateway: Pick<GraphGateway, "execute">;
+    telemetry?: TelemetrySink;
+    authorize?: AuthorizeHandler;
+    maxBodyBytes?: number;
 }
 interface GraphWriteHandlerOptions {
     coordinator: Pick<WriteCoordinator, "submit">;
+    telemetry?: TelemetrySink;
+    authorize?: AuthorizeHandler;
+    maxBodyBytes?: number;
 }
 declare const createGraphReadHandler: (options: GraphReadHandlerOptions) => HttpHandler;
 declare const createGraphWriteHandler: (options: GraphWriteHandlerOptions) => HttpHandler;
 
-export { type GraphReadHandlerOptions, type GraphWriteHandlerOptions, createGraphReadHandler, createGraphWriteHandler };
+export { type AuthorizeHandler, type GraphReadHandlerOptions, type GraphWriteHandlerOptions, type HandlerAuthContext, createGraphReadHandler, createGraphWriteHandler };

package/dist/index.d.ts

@@ -1,14 +1,27 @@
-import { HttpHandler } from '@azure/functions';
+import { HttpRequest, InvocationContext, HttpHandler } from '@azure/functions';
+import { TelemetrySink } from '@plasius/graph-contracts';
 import { GraphGateway } from '@plasius/graph-gateway-core';
 import { WriteCoordinator } from '@plasius/graph-write-coordinator';
 
+interface HandlerAuthContext {
+    operation: "read" | "write";
+    request: HttpRequest;
+    context: InvocationContext;
+}
+type AuthorizeHandler = (context: HandlerAuthContext) => Promise<boolean> | boolean;
 interface GraphReadHandlerOptions {
     gateway: Pick<GraphGateway, "execute">;
+    telemetry?: TelemetrySink;
+    authorize?: AuthorizeHandler;
+    maxBodyBytes?: number;
 }
 interface GraphWriteHandlerOptions {
     coordinator: Pick<WriteCoordinator, "submit">;
+    telemetry?: TelemetrySink;
+    authorize?: AuthorizeHandler;
+    maxBodyBytes?: number;
 }
 declare const createGraphReadHandler: (options: GraphReadHandlerOptions) => HttpHandler;
 declare const createGraphWriteHandler: (options: GraphWriteHandlerOptions) => HttpHandler;
 
-export { type GraphReadHandlerOptions, type GraphWriteHandlerOptions, createGraphReadHandler, createGraphWriteHandler };
+export { type AuthorizeHandler, type GraphReadHandlerOptions, type GraphWriteHandlerOptions, type HandlerAuthContext, createGraphReadHandler, createGraphWriteHandler };

package/dist/index.js

@@ -1,4 +1,38 @@
 // src/handlers.ts
+import { isGraphQuery } from "@plasius/graph-contracts";
+var DEFAULT_MAX_BODY_BYTES = 64 * 1024;
+var isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+var isSafeKey = (value) => /^[A-Za-z0-9:_-]+$/.test(value);
+var isWriteCommandPayloadValid = (value) => {
+  if (!isObject(value)) {
+    return false;
+  }
+  if (typeof value.idempotencyKey !== "string" || value.idempotencyKey.length === 0 || value.idempotencyKey.length > 128 || !isSafeKey(value.idempotencyKey)) {
+    return false;
+  }
+  if (typeof value.partitionKey !== "string" || value.partitionKey.length === 0 || value.partitionKey.length > 128 || !isSafeKey(value.partitionKey)) {
+    return false;
+  }
+  if (typeof value.aggregateKey !== "string" || value.aggregateKey.length === 0 || value.aggregateKey.length > 256 || !isSafeKey(value.aggregateKey)) {
+    return false;
+  }
+  if (!isObject(value.payload)) {
+    return false;
+  }
+  if (typeof value.submittedAtEpochMs !== "number" || !Number.isFinite(value.submittedAtEpochMs) || value.submittedAtEpochMs < 0) {
+    return false;
+  }
+  return value.actorId === void 0 || typeof value.actorId === "string" && value.actorId.length > 0 && value.actorId.length <= 128;
+};
+var HandlerValidationError = class extends Error {
+  status;
+  code;
+  constructor(status, code, message) {
+    super(message);
+    this.status = status;
+    this.code = code;
+  }
+};
 var jsonResponse = (status, body) => ({
   status,
   jsonBody: body,
@@ -7,34 +41,167 @@ var jsonResponse = (status, body) => ({
     "cache-control": "no-store"
   }
 });
+var getContentLength = (request) => {
+  const raw = request.headers?.get?.("content-length");
+  if (!raw) {
+    return null;
+  }
+  const parsed = Number.parseInt(raw, 10);
+  if (!Number.isFinite(parsed) || parsed < 0) {
+    return null;
+  }
+  return parsed;
+};
+var enforceBodyLimit = (request, maxBodyBytes) => {
+  const contentLength = getContentLength(request);
+  if (contentLength !== null && contentLength > maxBodyBytes) {
+    throw new HandlerValidationError(413, "GRAPH_REQUEST_BODY_TOO_LARGE", "Request payload exceeds allowed limit.");
+  }
+};
+var enforceAuthorization = async (authorize, operation, request, context) => {
+  if (!authorize) {
+    return;
+  }
+  const allowed = await authorize({ operation, request, context });
+  if (!allowed) {
+    throw new HandlerValidationError(403, "GRAPH_FORBIDDEN", "Forbidden");
+  }
+};
 var createGraphReadHandler = (options) => {
   return async (request, context) => {
+    const startedAt = Date.now();
+    options.telemetry?.metric({
+      name: "graph.runtime.read.request",
+      value: 1,
+      unit: "count"
+    });
     try {
-      const query = await request.json();
+      const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+      enforceBodyLimit(request, maxBodyBytes);
+      await enforceAuthorization(options.authorize, "read", request, context);
+      let rawBody;
+      try {
+        rawBody = await request.json();
+      } catch {
+        throw new HandlerValidationError(400, "GRAPH_READ_REQUEST_INVALID", "Invalid graph read request.");
+      }
+      if (!isGraphQuery(rawBody)) {
+        throw new HandlerValidationError(400, "GRAPH_READ_REQUEST_INVALID", "Invalid graph read request.");
+      }
+      const query = rawBody;
       const result = await options.gateway.execute({
         ...query,
         traceId: query.traceId ?? context.traceContext?.traceParent
       });
+      options.telemetry?.metric({
+        name: "graph.runtime.read.latency",
+        value: Date.now() - startedAt,
+        unit: "ms",
+        tags: { status: "200" }
+      });
       return jsonResponse(200, result);
     } catch (error) {
-      return jsonResponse(400, {
-        code: "GRAPH_READ_REQUEST_INVALID",
-        message: error instanceof Error ? error.message : "Invalid read request"
+      if (error instanceof HandlerValidationError) {
+        options.telemetry?.metric({
+          name: "graph.runtime.read.error",
+          value: 1,
+          unit: "count",
+          tags: { code: error.code }
+        });
+        options.telemetry?.error({
+          message: error.message,
+          source: "graph-runtime-azure-functions.read",
+          code: error.code
+        });
+        return jsonResponse(error.status, {
+          code: error.code,
+          message: error.message
+        });
+      }
+      options.telemetry?.metric({
+        name: "graph.runtime.read.error",
+        value: 1,
+        unit: "count",
+        tags: { code: "GRAPH_READ_UPSTREAM_FAILED" }
+      });
+      options.telemetry?.error({
+        message: "Graph read failed",
+        source: "graph-runtime-azure-functions.read",
+        code: "GRAPH_READ_UPSTREAM_FAILED"
+      });
+      return jsonResponse(502, {
+        code: "GRAPH_READ_UPSTREAM_FAILED",
+        message: "Graph read failed."
       });
     }
   };
 };
 var createGraphWriteHandler = (options) => {
-  return async (request) => {
+  return async (request, context) => {
+    const startedAt = Date.now();
+    options.telemetry?.metric({
+      name: "graph.runtime.write.request",
+      value: 1,
+      unit: "count"
+    });
     try {
-      const command = await request.json();
+      const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;
+      enforceBodyLimit(request, maxBodyBytes);
+      await enforceAuthorization(options.authorize, "write", request, context);
+      let rawBody;
+      try {
+        rawBody = await request.json();
+      } catch {
+        throw new HandlerValidationError(400, "GRAPH_WRITE_REQUEST_INVALID", "Invalid graph write request.");
+      }
+      if (!isWriteCommandPayloadValid(rawBody)) {
+        throw new HandlerValidationError(400, "GRAPH_WRITE_REQUEST_INVALID", "Invalid graph write request.");
+      }
+      const command = rawBody;
       const operation = await options.coordinator.submit(command);
       const status = operation.state === "succeeded" ? 200 : 202;
+      options.telemetry?.metric({
+        name: "graph.runtime.write.latency",
+        value: Date.now() - startedAt,
+        unit: "ms",
+        tags: {
+          status: String(status),
+          state: operation.state
+        }
+      });
       return jsonResponse(status, operation);
     } catch (error) {
-      return jsonResponse(400, {
-        code: "GRAPH_WRITE_REQUEST_INVALID",
-        message: error instanceof Error ? error.message : "Invalid write request"
+      if (error instanceof HandlerValidationError) {
+        options.telemetry?.metric({
+          name: "graph.runtime.write.error",
+          value: 1,
+          unit: "count",
+          tags: { code: error.code }
+        });
+        options.telemetry?.error({
+          message: error.message,
+          source: "graph-runtime-azure-functions.write",
+          code: error.code
+        });
+        return jsonResponse(error.status, {
+          code: error.code,
+          message: error.message
+        });
+      }
+      options.telemetry?.metric({
+        name: "graph.runtime.write.error",
+        value: 1,
+        unit: "count",
+        tags: { code: "GRAPH_WRITE_UPSTREAM_FAILED" }
+      });
+      options.telemetry?.error({
+        message: "Graph write failed",
+        source: "graph-runtime-azure-functions.write",
+        code: "GRAPH_WRITE_UPSTREAM_FAILED"
+      });
+      return jsonResponse(503, {
+        code: "GRAPH_WRITE_UPSTREAM_FAILED",
+        message: "Graph write failed."
       });
     }
   };

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/handlers.ts"],"sourcesContent":["import type { HttpHandler, HttpRequest, HttpResponseInit, InvocationContext } from \"@azure/functions\";\nimport type { GraphQuery, WriteCommand } from \"@plasius/graph-contracts\";\nimport type { GraphGateway } from \"@plasius/graph-gateway-core\";\nimport type { WriteCoordinator } from \"@plasius/graph-write-coordinator\";\n\nexport interface GraphReadHandlerOptions {\n  gateway: Pick<GraphGateway, \"execute\">;\n}\n\nexport interface GraphWriteHandlerOptions {\n  coordinator: Pick<WriteCoordinator, \"submit\">;\n}\n\nconst jsonResponse = (status: number, body: unknown): HttpResponseInit => ({\n  status,\n  jsonBody: body,\n  headers: {\n    \"content-type\": \"application/json\",\n    \"cache-control\": \"no-store\",\n  },\n});\n\nexport const createGraphReadHandler = (options: GraphReadHandlerOptions): HttpHandler => {\n  return async (request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> => {\n    try {\n      const query = (await request.json()) as GraphQuery;\n      const result = await options.gateway.execute({\n        ...query,\n        traceId: query.traceId ?? context.traceContext?.traceParent,\n      });\n      return jsonResponse(200, result);\n    } catch (error) {\n      return jsonResponse(400, {\n        code: \"GRAPH_READ_REQUEST_INVALID\",\n        message: error instanceof Error ? error.message : \"Invalid read request\",\n      });\n    }\n  };\n};\n\nexport const createGraphWriteHandler = (options: GraphWriteHandlerOptions): HttpHandler => {\n  return async (request: HttpRequest): Promise<HttpResponseInit> => {\n    try {\n      const command = (await request.json()) as WriteCommand;\n      const operation = await options.coordinator.submit(command);\n      const status = operation.state === \"succeeded\" ? 200 : 202;\n      return jsonResponse(status, operation);\n    } catch (error) {\n      return jsonResponse(400, {\n        code: \"GRAPH_WRITE_REQUEST_INVALID\",\n        message: error instanceof Error ? error.message : \"Invalid write request\",\n      });\n    }\n  };\n};\n"],"mappings":";AAaA,IAAM,eAAe,CAAC,QAAgB,UAAqC;AAAA,EACzE;AAAA,EACA,UAAU;AAAA,EACV,SAAS;AAAA,IACP,gBAAgB;AAAA,IAChB,iBAAiB;AAAA,EACnB;AACF;AAEO,IAAM,yBAAyB,CAAC,YAAkD;AACvF,SAAO,OAAO,SAAsB,YAA0D;AAC5F,QAAI;AACF,YAAM,QAAS,MAAM,QAAQ,KAAK;AAClC,YAAM,SAAS,MAAM,QAAQ,QAAQ,QAAQ;AAAA,QAC3C,GAAG;AAAA,QACH,SAAS,MAAM,WAAW,QAAQ,cAAc;AAAA,MAClD,CAAC;AACD,aAAO,aAAa,KAAK,MAAM;AAAA,IACjC,SAAS,OAAO;AACd,aAAO,aAAa,KAAK;AAAA,QACvB,MAAM;AAAA,QACN,SAAS,iBAAiB,QAAQ,MAAM,UAAU;AAAA,MACpD,CAAC;AAAA,IACH;AAAA,EACF;AACF;AAEO,IAAM,0BAA0B,CAAC,YAAmD;AACzF,SAAO,OAAO,YAAoD;AAChE,QAAI;AACF,YAAM,UAAW,MAAM,QAAQ,KAAK;AACpC,YAAM,YAAY,MAAM,QAAQ,YAAY,OAAO,OAAO;AAC1D,YAAM,SAAS,UAAU,UAAU,cAAc,MAAM;AACvD,aAAO,aAAa,QAAQ,SAAS;AAAA,IACvC,SAAS,OAAO;AACd,aAAO,aAAa,KAAK;AAAA,QACvB,MAAM;AAAA,QACN,SAAS,iBAAiB,QAAQ,MAAM,UAAU;AAAA,MACpD,CAAC;AAAA,IACH;AAAA,EACF;AACF;","names":[]}
+{"version":3,"sources":["../src/handlers.ts"],"sourcesContent":["import type { HttpHandler, HttpRequest, HttpResponseInit, InvocationContext } from \"@azure/functions\";\nimport { isGraphQuery, type GraphQuery, type TelemetrySink, type WriteCommand } from \"@plasius/graph-contracts\";\nimport type { GraphGateway } from \"@plasius/graph-gateway-core\";\nimport type { WriteCoordinator } from \"@plasius/graph-write-coordinator\";\n\nexport interface HandlerAuthContext {\n  operation: \"read\" | \"write\";\n  request: HttpRequest;\n  context: InvocationContext;\n}\n\nexport type AuthorizeHandler = (context: HandlerAuthContext) => Promise<boolean> | boolean;\n\nexport interface GraphReadHandlerOptions {\n  gateway: Pick<GraphGateway, \"execute\">;\n  telemetry?: TelemetrySink;\n  authorize?: AuthorizeHandler;\n  maxBodyBytes?: number;\n}\n\nexport interface GraphWriteHandlerOptions {\n  coordinator: Pick<WriteCoordinator, \"submit\">;\n  telemetry?: TelemetrySink;\n  authorize?: AuthorizeHandler;\n  maxBodyBytes?: number;\n}\n\nconst DEFAULT_MAX_BODY_BYTES = 64 * 1024;\n\nconst isObject = (value: unknown): value is Record<string, unknown> =>\n  value !== null && typeof value === \"object\" && !Array.isArray(value);\n\nconst isSafeKey = (value: string): boolean => /^[A-Za-z0-9:_-]+$/.test(value);\n\nconst isWriteCommandPayloadValid = (value: unknown): value is WriteCommand => {\n  if (!isObject(value)) {\n    return false;\n  }\n\n  if (\n    typeof value.idempotencyKey !== \"string\"\n    || value.idempotencyKey.length === 0\n    || value.idempotencyKey.length > 128\n    || !isSafeKey(value.idempotencyKey)\n  ) {\n    return false;\n  }\n\n  if (\n    typeof value.partitionKey !== \"string\"\n    || value.partitionKey.length === 0\n    || value.partitionKey.length > 128\n    || !isSafeKey(value.partitionKey)\n  ) {\n    return false;\n  }\n\n  if (\n    typeof value.aggregateKey !== \"string\"\n    || value.aggregateKey.length === 0\n    || value.aggregateKey.length > 256\n    || !isSafeKey(value.aggregateKey)\n  ) {\n    return false;\n  }\n\n  if (!isObject(value.payload)) {\n    return false;\n  }\n\n  if (typeof value.submittedAtEpochMs !== \"number\" || !Number.isFinite(value.submittedAtEpochMs) || value.submittedAtEpochMs < 0) {\n    return false;\n  }\n\n  return value.actorId === undefined || (typeof value.actorId === \"string\" && value.actorId.length > 0 && value.actorId.length <= 128);\n};\n\nclass HandlerValidationError extends Error {\n  public readonly status: number;\n  public readonly code: string;\n\n  public constructor(status: number, code: string, message: string) {\n    super(message);\n    this.status = status;\n    this.code = code;\n  }\n}\n\nconst jsonResponse = (status: number, body: unknown): HttpResponseInit => ({\n  status,\n  jsonBody: body,\n  headers: {\n    \"content-type\": \"application/json\",\n    \"cache-control\": \"no-store\",\n  },\n});\n\nconst getContentLength = (request: HttpRequest): number | null => {\n  const raw = request.headers?.get?.(\"content-length\");\n  if (!raw) {\n    return null;\n  }\n\n  const parsed = Number.parseInt(raw, 10);\n  if (!Number.isFinite(parsed) || parsed < 0) {\n    return null;\n  }\n\n  return parsed;\n};\n\nconst enforceBodyLimit = (request: HttpRequest, maxBodyBytes: number): void => {\n  const contentLength = getContentLength(request);\n  if (contentLength !== null && contentLength > maxBodyBytes) {\n    throw new HandlerValidationError(413, \"GRAPH_REQUEST_BODY_TOO_LARGE\", \"Request payload exceeds allowed limit.\");\n  }\n};\n\nconst enforceAuthorization = async (\n  authorize: AuthorizeHandler | undefined,\n  operation: \"read\" | \"write\",\n  request: HttpRequest,\n  context: InvocationContext,\n): Promise<void> => {\n  if (!authorize) {\n    return;\n  }\n\n  const allowed = await authorize({ operation, request, context });\n  if (!allowed) {\n    throw new HandlerValidationError(403, \"GRAPH_FORBIDDEN\", \"Forbidden\");\n  }\n};\n\nexport const createGraphReadHandler = (options: GraphReadHandlerOptions): HttpHandler => {\n  return async (request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> => {\n    const startedAt = Date.now();\n    options.telemetry?.metric({\n      name: \"graph.runtime.read.request\",\n      value: 1,\n      unit: \"count\",\n    });\n    try {\n      const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;\n      enforceBodyLimit(request, maxBodyBytes);\n      await enforceAuthorization(options.authorize, \"read\", request, context);\n\n      let rawBody: unknown;\n      try {\n        rawBody = await request.json();\n      } catch {\n        throw new HandlerValidationError(400, \"GRAPH_READ_REQUEST_INVALID\", \"Invalid graph read request.\");\n      }\n      if (!isGraphQuery(rawBody)) {\n        throw new HandlerValidationError(400, \"GRAPH_READ_REQUEST_INVALID\", \"Invalid graph read request.\");\n      }\n\n      const query = rawBody as GraphQuery;\n      const result = await options.gateway.execute({\n        ...query,\n        traceId: query.traceId ?? context.traceContext?.traceParent,\n      });\n      options.telemetry?.metric({\n        name: \"graph.runtime.read.latency\",\n        value: Date.now() - startedAt,\n        unit: \"ms\",\n        tags: { status: \"200\" },\n      });\n      return jsonResponse(200, result);\n    } catch (error) {\n      if (error instanceof HandlerValidationError) {\n        options.telemetry?.metric({\n          name: \"graph.runtime.read.error\",\n          value: 1,\n          unit: \"count\",\n          tags: { code: error.code },\n        });\n        options.telemetry?.error({\n          message: error.message,\n          source: \"graph-runtime-azure-functions.read\",\n          code: error.code,\n        });\n        return jsonResponse(error.status, {\n          code: error.code,\n          message: error.message,\n        });\n      }\n\n      options.telemetry?.metric({\n        name: \"graph.runtime.read.error\",\n        value: 1,\n        unit: \"count\",\n        tags: { code: \"GRAPH_READ_UPSTREAM_FAILED\" },\n      });\n      options.telemetry?.error({\n        message: \"Graph read failed\",\n        source: \"graph-runtime-azure-functions.read\",\n        code: \"GRAPH_READ_UPSTREAM_FAILED\",\n      });\n      return jsonResponse(502, {\n        code: \"GRAPH_READ_UPSTREAM_FAILED\",\n        message: \"Graph read failed.\",\n      });\n    }\n  };\n};\n\nexport const createGraphWriteHandler = (options: GraphWriteHandlerOptions): HttpHandler => {\n  return async (request: HttpRequest, context: InvocationContext): Promise<HttpResponseInit> => {\n    const startedAt = Date.now();\n    options.telemetry?.metric({\n      name: \"graph.runtime.write.request\",\n      value: 1,\n      unit: \"count\",\n    });\n    try {\n      const maxBodyBytes = options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES;\n      enforceBodyLimit(request, maxBodyBytes);\n      await enforceAuthorization(options.authorize, \"write\", request, context);\n\n      let rawBody: unknown;\n      try {\n        rawBody = await request.json();\n      } catch {\n        throw new HandlerValidationError(400, \"GRAPH_WRITE_REQUEST_INVALID\", \"Invalid graph write request.\");\n      }\n      if (!isWriteCommandPayloadValid(rawBody)) {\n        throw new HandlerValidationError(400, \"GRAPH_WRITE_REQUEST_INVALID\", \"Invalid graph write request.\");\n      }\n\n      const command = rawBody as WriteCommand;\n      const operation = await options.coordinator.submit(command);\n      const status = operation.state === \"succeeded\" ? 200 : 202;\n      options.telemetry?.metric({\n        name: \"graph.runtime.write.latency\",\n        value: Date.now() - startedAt,\n        unit: \"ms\",\n        tags: {\n          status: String(status),\n          state: operation.state,\n        },\n      });\n      return jsonResponse(status, operation);\n    } catch (error) {\n      if (error instanceof HandlerValidationError) {\n        options.telemetry?.metric({\n          name: \"graph.runtime.write.error\",\n          value: 1,\n          unit: \"count\",\n          tags: { code: error.code },\n        });\n        options.telemetry?.error({\n          message: error.message,\n          source: \"graph-runtime-azure-functions.write\",\n          code: error.code,\n        });\n        return jsonResponse(error.status, {\n          code: error.code,\n          message: error.message,\n        });\n      }\n\n      options.telemetry?.metric({\n        name: \"graph.runtime.write.error\",\n        value: 1,\n        unit: \"count\",\n        tags: { code: \"GRAPH_WRITE_UPSTREAM_FAILED\" },\n      });\n      options.telemetry?.error({\n        message: \"Graph write failed\",\n        source: \"graph-runtime-azure-functions.write\",\n        code: \"GRAPH_WRITE_UPSTREAM_FAILED\",\n      });\n      return jsonResponse(503, {\n        code: \"GRAPH_WRITE_UPSTREAM_FAILED\",\n        message: \"Graph write failed.\",\n      });\n    }\n  };\n};\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plasius/graph-runtime-azure-functions",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Azure Functions runtime adapter for graph gateway read/write endpoints",
   "type": "module",
   "sideEffects": false,