Get Started

This guide walks through configuring Gateway from backend({ gateway }).

1. Add Gateway Config

Configure Gateway when you create the backend app:

import { backend } from "@layeron/core"

const app = backend({
  project: "acme",
  endpoint: "https://api.example.com",
  gateway: {
    defaultAuth: "public",
    cors: {
      origins: ["https://app.example.com"],
      methods: ["GET", "POST"],
      requestHeaders: ["content-type", "authorization"],
      responseHeaders: ["x-layeron-request-id"],
      credentials: true,
      maxAgeSeconds: 600,
    },
    requestIdHeader: "x-request-id",
    responseRequestIdHeader: "x-layeron-request-id",
    traceHeader: "traceparent",
    logs: {
      level: "error",
      request: false,
      cors: true,
      routeMatch: false,
      errors: true,
      includeHeaders: ["origin", "content-type"],
      redactHeaders: ["authorization", "cookie"],
      sampling: {
        success: 0.01,
        error: 1,
      },
    },
  },
})

2. Set The Default Auth Policy

gateway.defaultAuth applies to routes that omit auth. The default value is public.

const app = backend({
  project: "acme",
  gateway: {
    defaultAuth: "user",
  },
})

app.get("/account", async () => {
  return { ok: true }
})

app.get("/status", { auth: "public" }, async () => {
  return { ok: true }
})

Supported route policies are public, user, service, and admin. service and admin routes use the Auth Product resolveSubject result. Service routes accept a service subject or a subject with the service role or scope. Admin routes accept a subject with the admin role or scope.

3. Configure CORS

gateway.cors applies to generated Gateway responses and route handler responses. Preflight requests return 204 when the path exists and the origin, method, and requested headers match the configured policy.

gateway: {
  cors: {
    origins: ["https://app.example.com"],
    methods: ["GET", "POST"],
    requestHeaders: ["content-type", "authorization"],
    responseHeaders: ["x-layeron-request-id"],
    credentials: true,
    maxAgeSeconds: 600,
  },
}

Use exact origins for production browser apps:

gateway: {
  cors: {
    origins: [
      "https://app.example.com",
      "https://admin.example.com",
    ],
    credentials: true,
  },
}

If credentials is enabled, browsers require a concrete Access-Control-Allow-Origin value. Gateway echoes the matched request origin for configured origins.

Gateway returns 404 for preflight requests to undeclared paths. Gateway returns 403 when the origin, method, or requested headers are outside the policy.

4. Configure Request Identity

Gateway reads requestIdHeader from incoming requests and writes the selected responseRequestIdHeader on responses. It reads traceHeader and stores the value in runtime context for logs, metrics, and product calls.

Default headers:

Field	Default
requestIdHeader	x-request-id
responseRequestIdHeader	x-layeron-request-id
traceHeader	traceparent

If the request id header is missing, Gateway falls back to Cloudflare cf-ray and then generates a request id.

5. Configure Gateway Logs

Gateway product logs use the reserved stream identity:

{
  namespace: "layeron",
  name: "gateway",
}

The default production posture is conservative: error records are retained, normal request records require explicit opt-in through gateway.logs.

gateway: {
  logs: {
    level: "warn",
    request: true,
    cors: true,
    routeMatch: true,
    errors: true,
    includeHeaders: ["origin", "content-type"],
    redactHeaders: ["authorization", "cookie"],
    sampling: {
      success: 0.05,
      error: 1,
    },
  },
}

Gateway never records request bodies. Header recording uses an allowlist through includeHeaders, and sensitive headers are redacted before emission.

Next Steps

• Runtime behavior: Review routing, auth policy, CORS, error responses, Gateway logs, current boundaries, and security notes.
• Backend routes: Define public routes, handlers, and route metadata in your backend app.
• Log: Emit structured logs from route and runtime code.
• API reference: Review Gateway config, CORS, logging, backend options, and app methods.