@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, validated with 4.16.x)
• @plasius/graph-gateway-core 0.1.11+
• @plasius/graph-write-coordinator 0.1.11+

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 ci
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

Telemetry stays privacy-minimized by design:

• emitted error events carry only the generic translated message, stable error code, and handler source;
• the adapter does not serialize request bodies, resolver params, write payloads, graph result data, or raw upstream exception text into telemetry;
• host applications should keep downstream telemetry sinks aligned with the same minimal schema.

Runtime Privacy Guidance

The package exports GRAPH_RUNTIME_AZURE_FUNCTIONS_PRIVACY_GUIDANCE to make the runtime privacy boundary explicit for rollout reviews and host integrations.

• telemetry-minimization
  • telemetry is limited to generic outcome data and must never include graph payloads or raw upstream diagnostics
• bounded-error-responses
  • handler-generated 400/403/413/502/503 responses expose only stable codes plus translated generic messages
• authorized-success-payloads
  • successful 200/202 payloads pass through the upstream gateway/coordinator result, so upstream services remain responsible for omitting or redacting secret material before it reaches this adapter

The adapter intentionally sets Cache-Control: no-store on JSON responses, but it does not inspect or rewrite successful graph payloads on your behalf.

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.

Release integrity

CI keeps the administrative contributor registry outside Git and npm package artifacts using exact, case-normalised path checks. CI runs on approved GitHub-hosted runners for same-repository pull requests and main, with package-manager cache finalization disabled; fork PR code is denied. Publication uses the GitHub-hosted production job with Node 24 and a pinned npm 11.6.2 client. It is token-free and proceeds only while the prepared SHA is the exact main head after successful push-triggered CI. Do not dispatch CD until the npm trusted-publisher binding is verified.