@plasius/graph-runtime-azure-functions

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 @azure/functions

Exports

import {
  createGraphReadHandler,
  createGraphWriteHandler,
  type GraphReadHandlerOptions,
  type GraphWriteHandlerOptions,
} from "@plasius/graph-runtime-azure-functions";

Quick Start

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, authorize }),
});

app.http("graph-write", {
  methods: ["POST"],
  authLevel: "function",
  handler: createGraphWriteHandler({ coordinator, telemetry, authorize }),
});

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).
• Authorization is fail-closed. Handlers require authorize(context) by default and return 403 when the guard is missing or denies access.
• Intentional public handlers must set allowAnonymous: true explicitly.

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

Error bodies keep the existing code and message fields and add translation metadata so clients can resolve display text through @plasius/translations:

{
  "code": "GRAPH_READ_UPSTREAM_FAILED",
  "message": "Graph read failed.",
  "messageKey": "graphRuntimeAzureFunctions.error.readUpstreamFailed.message",
  "messageDefault": "Graph read failed."
}

import { createI18n } from "@plasius/translations";
import { graphRuntimeAzureFunctionsTranslations } from "@plasius/graph-runtime-azure-functions";

const i18n = createI18n({
  language: "en-GB",
  fallback: "en-GB",
  translations: graphRuntimeAzureFunctionsTranslations,
});

Development

npm run clean
npm install
npm run lint
npm run typecheck
npm run test:coverage
npm run build

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

• Package ADRs: docs/adrs
• Cross-package ADRs: plasius-ltd-site/docs/adrs/adr-0020 to adr-0024

License

Licensed under the Apache-2.0 License.