📦 deps(thirdparty): update snapshots
This commit is contained in:
ci[bot]
@@ -0,0 +1,139 @@
|
||||
# AI SDK agents on Neon Functions
|
||||
|
||||
A Neon Function is a long-lived Node.js 24 process, which makes it a natural host for a [Vercel AI SDK](https://ai-sdk.dev) agent: the handler keeps streaming for the life of the request (15-minute budget, see [Timeouts](../SKILL.md#timeouts-and-runtime-limits)), so multi-step tool loops and image/video generation don't get cut off the way they do on lambda-style serverless. Point the model at the **Neon AI Gateway** (see the `neon-ai-gateway` skill) and there are no extra provider keys to manage — one Neon credential reaches the whole catalog.
|
||||
|
||||
The AI SDK is the **recommended** way to build agents on Functions from TypeScript: one set of primitives (`streamText`, `generateText`, tool calling, structured output) over every catalog model. For a memory- and workflow-heavy agent with built-in tracing, use Mastra instead (see [references/mastra-studio.md](mastra-studio.md)); both point at the same gateway.
|
||||
|
||||
The pattern below is a complete agent: it streams chat and, when asked, generates an image, uploads it to Object Storage, and indexes it in Postgres.
|
||||
|
||||
## 1. Declare the gateway and the function
|
||||
|
||||
The agent needs the AI Gateway (and, for the image example, an Object Storage bucket). Declare both in `neon.ts` alongside the function — `neon deploy` provisions them and injects the credentials at runtime (see the `neon-ai-gateway` and `neon-object-storage` skills):
|
||||
|
||||
```typescript
|
||||
// neon.ts
|
||||
import { defineConfig } from "@neon/config/v1";
|
||||
|
||||
export default defineConfig({
|
||||
preview: {
|
||||
aiGateway: true,
|
||||
buckets: { images: {} },
|
||||
functions: {
|
||||
agent: { name: "ai agent", source: "src/index.ts" },
|
||||
},
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
## 2. The handler: stream a tool-calling agent
|
||||
|
||||
The function's default export is a web-standard `{ fetch }` handler. The `@neon/ai-sdk-provider` reads the injected gateway credentials automatically, so `neon("<model>")` is all the model config you need — it routes each model to the right dialect (Anthropic → Messages, OpenAI/Codex → Responses, everything else → MLflow). Return `result.toUIMessageStreamResponse()` so the AI SDK's `useChat` hooks can consume the stream:
|
||||
|
||||
```typescript
|
||||
// src/index.ts
|
||||
import { neon } from "@neon/ai-sdk-provider";
|
||||
import { streamText, tool, stepCountIs, type ModelMessage } from "ai";
|
||||
import { z } from "zod";
|
||||
import { drizzle } from "drizzle-orm/node-postgres";
|
||||
import { Pool } from "pg";
|
||||
import { todos } from "./db/schema";
|
||||
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
|
||||
const db = drizzle(pool);
|
||||
|
||||
export default {
|
||||
async fetch(request: Request) {
|
||||
if (request.method !== "POST") {
|
||||
return new Response("POST chat messages here", { status: 405 });
|
||||
}
|
||||
const { messages } = (await request.json()) as { messages: ModelMessage[] };
|
||||
|
||||
const result = streamText({
|
||||
model: neon("claude-sonnet-4-6"), // swap to gpt-5-mini, gemini-2-5-flash, …
|
||||
system: "You are a concise assistant with access to the user's todos.",
|
||||
messages,
|
||||
tools: {
|
||||
countOpenTodos: tool({
|
||||
description: "Count the user's open todos.",
|
||||
inputSchema: z.object({}),
|
||||
execute: async () => ({ open: await db.$count(todos) }),
|
||||
}),
|
||||
},
|
||||
// Let the model call tools and then summarize, instead of stopping after
|
||||
// the first tool call. The loop runs in-process — no host timeout.
|
||||
stopWhen: stepCountIs(5),
|
||||
onError({ error }) {
|
||||
console.error("[streamText] error:", error);
|
||||
},
|
||||
});
|
||||
|
||||
return result.toUIMessageStreamResponse({
|
||||
onError: (error) => (error instanceof Error ? error.message : String(error)),
|
||||
});
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
`tool({ inputSchema, execute })` is the AI SDK v5+ shape (the parameter is `inputSchema`, not the old `parameters`). The tool's `execute` runs **inside the function**, right next to Postgres — no extra network hop.
|
||||
|
||||
## 3. Generate images and persist them
|
||||
|
||||
The gateway exposes the OpenAI Responses **`image_generation`** built-in tool (GPT-5 models only; the image comes back inline as base64). Persist generated assets to Object Storage and index them in Postgres so they branch together — the **recommended** storage client is the Files SDK `neon` adapter (see the `neon-object-storage` skill):
|
||||
|
||||
```typescript
|
||||
import { neon } from "@neon/ai-sdk-provider";
|
||||
import { streamText } from "ai";
|
||||
import { Files } from "files-sdk";
|
||||
import { neon as neonFiles } from "files-sdk/neon";
|
||||
import { randomUUID } from "node:crypto";
|
||||
|
||||
const files = new Files({ adapter: neonFiles({ bucket: "images" }) });
|
||||
|
||||
const result = streamText({
|
||||
model: neon("gpt-5-mini"),
|
||||
system: "Use image_generation when the user asks for a picture, then describe it.",
|
||||
messages,
|
||||
tools: {
|
||||
image_generation: neon.tools.imageGeneration({
|
||||
outputFormat: "jpeg",
|
||||
quality: "low", // the gateway caps a response near 640 KB — keep images small
|
||||
size: "1024x1024",
|
||||
}),
|
||||
},
|
||||
async onStepFinish({ toolResults }) {
|
||||
for (const tr of toolResults) {
|
||||
if (tr.toolName !== "image_generation") continue;
|
||||
const base64 = imageResultBase64(tr.output);
|
||||
if (!base64) continue;
|
||||
const key = `generated/${randomUUID()}.jpg`;
|
||||
await files.upload(key, Buffer.from(base64, "base64"), { contentType: "image/jpeg" });
|
||||
// …insert a row keyed by `key` into Postgres; serve later via files.url(key)
|
||||
}
|
||||
},
|
||||
});
|
||||
```
|
||||
|
||||
Keep generated images small: the gateway caps a single response near 640 KB and has an upstream timeout, so request a compressed JPEG rather than a full-size PNG.
|
||||
|
||||
## 4. Call it directly from the client (don't proxy the stream)
|
||||
|
||||
So the long stream isn't cut off by your web host's serverless limits, have the **browser call the function directly** and authenticate at the top of the handler — see [Functions as an agent backend](../SKILL.md#functions-as-an-agent-backend-nextjs-and-similar-frameworks) for the JWT-verify + CORS pattern and the AI SDK `DefaultChatTransport` wiring.
|
||||
|
||||
## 5. Run and deploy
|
||||
|
||||
```bash
|
||||
neon dev # injects DATABASE_URL + the gateway/storage creds; hot reload
|
||||
neon deploy # provisions the gateway + bucket and deploys the function
|
||||
```
|
||||
|
||||
```bash
|
||||
curl -N -X POST "$(neon functions get agent -o json | jq -r .invocation_url)" \
|
||||
-H "content-type: application/json" \
|
||||
-d '{"messages":[{"role":"user","content":"How many open todos do I have?"}]}'
|
||||
```
|
||||
|
||||
## Further reading
|
||||
|
||||
- Neon AI Gateway dialects, models, and the `@neon/ai-sdk-provider`: the `neon-ai-gateway` skill
|
||||
- Storing generated assets that branch with the database: the `neon-object-storage` skill
|
||||
- AI SDK agents/tools: https://ai-sdk.dev/docs/foundations/agents
|
||||
@@ -0,0 +1,145 @@
|
||||
# Hono WebSocket helper on Neon Functions
|
||||
|
||||
Neon Functions accept WebSockets via a `{ fetch, upgrade }` default export, where `upgrade(req, socket, head)` is the raw Node handshake (see the [WebSocket servers](../SKILL.md#websocket-servers) section). That works directly with the `ws` library. If you'd rather declare WebSocket routes _inside_ a Hono app — `app.get("/ws", upgradeWebSocket(...))` with the standard `onOpen`/`onMessage`/`onClose` lifecycle — you need an adapter.
|
||||
|
||||
## Why an adapter (and why not `@hono/node-ws`)
|
||||
|
||||
Hono's `upgradeWebSocket()` is runtime-agnostic at the route layer, but the actual handshake is done by a per-runtime adapter (`hono/cloudflare-workers`, `hono/deno`, `hono/bun`, `@hono/node-server`). **There is no adapter for Neon.** The Node one, `@hono/node-ws`, is **deprecated** and its replacement assumes it owns the HTTP server (`serve({ websocket })`) — which Neon's runtime does instead.
|
||||
|
||||
So vendor the small adapter below. It depends only on `hono` and `ws` (no deprecated package), and is adapted from `@hono/node-ws` (MIT). Instead of attaching to an `http.Server`'s `'upgrade'` event, it returns a ready-to-export `{ fetch, upgrade }` handler that matches Neon's contract.
|
||||
|
||||
## The adapter
|
||||
|
||||
```typescript
|
||||
// src/hono-ws.ts — bridges Hono's upgradeWebSocket() to Neon's { fetch, upgrade }.
|
||||
import { STATUS_CODES, type IncomingMessage } from "node:http";
|
||||
import type { Duplex } from "node:stream";
|
||||
import type { Hono } from "hono";
|
||||
import { WSContext, defineWebSocketHelper } from "hono/ws";
|
||||
import { WebSocketServer, type WebSocket } from "ws";
|
||||
|
||||
type Wire = (ws: WebSocket) => void;
|
||||
|
||||
export function createNeonWebSocket(app: Hono, baseUrl = "http://localhost") {
|
||||
const wss = new WebSocketServer({ noServer: true });
|
||||
// Correlate a handshake to its route handler via the per-request env object identity.
|
||||
const pending = new Map<unknown, Wire>();
|
||||
|
||||
const upgradeWebSocket = defineWebSocketHelper(async (c, events, options) => {
|
||||
if (c.req.header("upgrade")?.toLowerCase() !== "websocket") return;
|
||||
const url = c.req.url;
|
||||
pending.set(c.env, (ws) => {
|
||||
const onError = options?.onError ?? ((e: unknown) => console.error(e));
|
||||
const ctx = new WSContext<WebSocket>({
|
||||
send: (data, opts) => ws.send(data, { compress: opts?.compress }),
|
||||
close: (code, reason) => ws.close(code, reason),
|
||||
raw: ws,
|
||||
url,
|
||||
protocol: ws.protocol,
|
||||
get readyState() {
|
||||
return ws.readyState;
|
||||
},
|
||||
});
|
||||
try {
|
||||
events.onOpen?.(new Event("open"), ctx);
|
||||
} catch (e) {
|
||||
onError(e);
|
||||
}
|
||||
ws.on("message", (data, isBinary) => {
|
||||
for (const chunk of Array.isArray(data) ? data : [data]) {
|
||||
try {
|
||||
const payload = isBinary
|
||||
? chunk instanceof ArrayBuffer
|
||||
? chunk
|
||||
: chunk.buffer.slice(chunk.byteOffset, chunk.byteOffset + chunk.byteLength)
|
||||
: chunk.toString("utf-8");
|
||||
events.onMessage?.(new MessageEvent("message", { data: payload }), ctx);
|
||||
} catch (e) {
|
||||
onError(e);
|
||||
}
|
||||
}
|
||||
});
|
||||
ws.on("close", (code, reason) => {
|
||||
try {
|
||||
events.onClose?.(new CloseEvent("close", { code, reason: reason.toString() }), ctx);
|
||||
} catch (e) {
|
||||
onError(e);
|
||||
}
|
||||
});
|
||||
// Node 24 has no global ErrorEvent; a browser's ws.onerror gets a plain Event anyway.
|
||||
ws.on("error", (error) => {
|
||||
onError(error);
|
||||
try {
|
||||
events.onError?.(new Event("error"), ctx);
|
||||
} catch (e) {
|
||||
onError(e);
|
||||
}
|
||||
});
|
||||
});
|
||||
return new Response();
|
||||
});
|
||||
|
||||
const handler = {
|
||||
fetch: (request: Request) => app.fetch(request),
|
||||
async upgrade(req: IncomingMessage, socket: Duplex, head: Buffer) {
|
||||
const url = new URL(req.url ?? "/", baseUrl);
|
||||
const headers = new Headers();
|
||||
for (const [key, value] of Object.entries(req.headers)) {
|
||||
if (value) headers.append(key, Array.isArray(value) ? value[0] : value);
|
||||
}
|
||||
// The env object identity links this request back to the route handler above.
|
||||
const env = { incoming: req, outgoing: undefined };
|
||||
const response = await app.request(url, { headers }, env);
|
||||
const wire = pending.get(env);
|
||||
pending.delete(env);
|
||||
if (!wire) {
|
||||
socket.end(`HTTP/1.1 ${response.status} ${STATUS_CODES[response.status] ?? ""}\r\nConnection: close\r\nContent-Length: 0\r\n\r\n`);
|
||||
return;
|
||||
}
|
||||
wss.handleUpgrade(req, socket, head, (ws) => wire(ws));
|
||||
},
|
||||
};
|
||||
|
||||
return { upgradeWebSocket, handler };
|
||||
}
|
||||
```
|
||||
|
||||
How it works: the `upgrade` handler runs the handshake request through `app.request(...)` so Hono's router matches the `upgradeWebSocket` route; the helper registers a `wire` callback keyed by the per-request `env` object; if a route matched, `wss.handleUpgrade` accepts the socket and `wire` attaches the lifecycle handlers, otherwise the socket is closed with the route's status (e.g. 401/404).
|
||||
|
||||
## Usage
|
||||
|
||||
Because the handshake is routed through `app.request`, **auth and other gating are just normal Hono middleware on the route** — verify the `?token=` and return 401 before the upgrade:
|
||||
|
||||
```typescript
|
||||
// src/index.ts
|
||||
import { Hono } from "hono";
|
||||
import { createNeonWebSocket } from "./hono-ws";
|
||||
|
||||
const app = new Hono();
|
||||
const { upgradeWebSocket, handler } = createNeonWebSocket(app);
|
||||
|
||||
app.get("/", (c) => c.text("ok"));
|
||||
|
||||
app.get(
|
||||
"/ws",
|
||||
async (c, next) => {
|
||||
const identity = await verifyToken(c.req.query("token")); // your JWT check
|
||||
if (!identity) return c.text("Unauthorized", 401);
|
||||
await next();
|
||||
},
|
||||
upgradeWebSocket(() => ({
|
||||
onOpen: (_evt, ws) => ws.send("welcome"),
|
||||
onMessage: (evt, ws) => ws.send(`echo: ${evt.data}`),
|
||||
onClose: () => console.log("disconnected"),
|
||||
})),
|
||||
);
|
||||
|
||||
export default handler; // Neon's { fetch, upgrade } contract
|
||||
```
|
||||
|
||||
## Caveats
|
||||
|
||||
- **No header-modifying middleware on the WS route.** Per [Hono's docs](https://hono.dev/docs/helpers/websocket), middleware that changes headers (e.g. CORS) on an `upgradeWebSocket` route throws ("can't modify immutable headers"), because the helper rewrites headers internally. Auth middleware that only reads the query/headers and returns 401 is fine.
|
||||
- **Send a heartbeat.** A socket is dropped once it goes silent — Neon's window is 15 minutes ([Timeouts](../SKILL.md#timeouts-and-runtime-limits)), but intermediary proxies are usually far stricter (tens of seconds). Send a keepalive every ~25–30s so the connection never goes quiet. With the raw `ws` socket use `ws.ping()` (the browser auto-replies with a pong); through this helper you don't hold the raw socket, so send an app-level `ws.send("ping")` the client ignores instead. See [Heartbeat](../SKILL.md#heartbeat-keep-the-socket-alive).
|
||||
- **Fan-out and reconnect still apply.** This adapter only covers the per-isolate handshake. For a genuinely shared chat across isolates, broadcast with Postgres `LISTEN`/`NOTIFY`, and have clients reconnect with backoff — see [Fan-out across isolates](../SKILL.md#fan-out-across-isolates-do-not-skip-this) and [Client must reconnect](../SKILL.md#client-must-reconnect).
|
||||
- **Node-only globals.** Relies on `Event`, `MessageEvent`, and `CloseEvent` (all present on Neon's Node 24 runtime). `ErrorEvent` is intentionally avoided since it isn't a Node global.
|
||||
@@ -0,0 +1,132 @@
|
||||
# Mastra agents with Mastra Studio observability
|
||||
|
||||
A Neon Function is a long-lived Node.js 24 process, which makes it a natural host for a [Mastra](https://mastra.ai) agent: the agent keeps running for the life of the request, and you point its model at the Neon AI Gateway so there are no extra provider keys. You can keep **running the agent on Neon Functions** while shipping its traces to a **Mastra Studio (Mastra Cloud) project** for observability — the agent runs on Neon, the traces are viewable in Mastra.
|
||||
|
||||
The shape mirrors any other Node integration (see `references/sentry.md`): instantiate at module load, gate on env vars so local dev and unconfigured branches stay a no-op, and pass secrets at deploy time via `neon.ts`. `@mastra/core` and `@mastra/observability` bundle cleanly through `neon deploy`'s esbuild with no extra config.
|
||||
|
||||
## 1. Define the agent against the Neon AI Gateway
|
||||
|
||||
Use the gateway's **MLflow (chat-completions) dialect**, which serves every provider (OpenAI, Anthropic, …) — derive it from the injected `aiGateway.baseUrl` (see the `neon-ai-gateway` skill). `parseEnv` reads the injected gateway credentials from your `neon.ts`.
|
||||
|
||||
```typescript
|
||||
// src/mastra/agents/pricing.ts
|
||||
import { Agent } from "@mastra/core/agent";
|
||||
import { parseEnv } from "@neon/env";
|
||||
import config from "../../../neon";
|
||||
|
||||
const env = parseEnv(config);
|
||||
const gatewayUrl = env.aiGateway.baseUrl.replace("/openai/v1", "/mlflow/v1");
|
||||
|
||||
export const pricingAgent = new Agent({
|
||||
id: "pricing-analyst",
|
||||
name: "pricing-analyst",
|
||||
instructions: "You are a meticulous pricing analyst. …",
|
||||
model: { id: "neon/gpt-5-mini", url: gatewayUrl, apiKey: env.aiGateway.apiKey },
|
||||
});
|
||||
```
|
||||
|
||||
## 2. Wire observability to Mastra Studio
|
||||
|
||||
The `MastraPlatformExporter` (from `@mastra/observability`) sends traces to a Mastra Studio project. It reads `MASTRA_PLATFORM_ACCESS_TOKEN` and `MASTRA_PROJECT_ID` from the environment.
|
||||
|
||||
Gotcha: `Observability` requires **at least one exporter** — passing an empty `exporters` array throws `OBSERVABILITY_INVALID_INSTANCE_CONFIG`. So omit the `observability` option entirely until the platform creds are present, keeping the app runnable before the Mastra project exists (and in local dev).
|
||||
|
||||
```typescript
|
||||
// src/mastra/index.ts
|
||||
import { Mastra } from "@mastra/core/mastra";
|
||||
import { Observability, MastraPlatformExporter } from "@mastra/observability";
|
||||
import { pricingAgent } from "./agents/pricing";
|
||||
|
||||
const platformReady = Boolean(
|
||||
process.env.MASTRA_PLATFORM_ACCESS_TOKEN && process.env.MASTRA_PROJECT_ID,
|
||||
);
|
||||
|
||||
const observability = platformReady
|
||||
? new Observability({
|
||||
configs: {
|
||||
default: { serviceName: "my-app", exporters: [new MastraPlatformExporter()] },
|
||||
},
|
||||
})
|
||||
: undefined;
|
||||
|
||||
export const mastra = new Mastra({
|
||||
agents: { pricingAgent },
|
||||
...(observability ? { observability } : {}),
|
||||
});
|
||||
```
|
||||
|
||||
Agents must be **registered on the `Mastra` instance** (the `agents` map) for their `.generate()` / `.stream()` calls to be traced. Call them via `mastra.getAgent("pricingAgent")`.
|
||||
|
||||
## 3. Structured output through the gateway
|
||||
|
||||
The gateway does not enforce **native** structured output, so a bare `structuredOutput: { schema }` can come back missing fields (e.g. a nested `meta` object), failing Zod validation. Set `jsonPromptInjection: true` so Mastra injects the schema into the prompt and the model returns the full shape:
|
||||
|
||||
```typescript
|
||||
const agent = mastra.getAgent("pricingAgent");
|
||||
const result = await agent.generate(prompt, {
|
||||
structuredOutput: { schema: myZodSchema, jsonPromptInjection: true },
|
||||
abortSignal: AbortSignal.timeout(70_000), // bound each attempt; the gateway has an upstream timeout
|
||||
});
|
||||
const data = result.object; // validated against myZodSchema
|
||||
```
|
||||
|
||||
For resilience, register a second agent on a different model (e.g. `neon/claude-haiku-4-5`) and fall back to it if the primary attempt throws — the same provider-fallback pattern works because both are reachable on the MLflow dialect.
|
||||
|
||||
## 4. Create the Mastra project + token with the CLI
|
||||
|
||||
Install the Mastra CLI (`npm i -g mastra`) and authenticate. Project/token creation needs a **live login session**:
|
||||
|
||||
```bash
|
||||
mastra auth login # opens a browser; required before the steps below
|
||||
mastra auth whoami # shows your user + org id (org_…)
|
||||
```
|
||||
|
||||
- **Access token (non-interactive):** `mastra auth tokens create <name>` prints a one-time secret (`sk_…`). This is your `MASTRA_PLATFORM_ACCESS_TOKEN`.
|
||||
- **Project:** the interactive `mastra studio projects create` TUI is hard to script. Instead, register the project as part of a Studio deploy, which is non-interactive with `-y` and writes the project id to `.mastra-project.json`:
|
||||
|
||||
```bash
|
||||
mastra studio deploy --org org_xxx --project my-app -y
|
||||
# → .mastra-project.json: { "projectId": "…", "projectName": "my-app", "organizationId": "org_…" }
|
||||
```
|
||||
|
||||
Use that `projectId` as `MASTRA_PROJECT_ID`.
|
||||
|
||||
Two gotchas:
|
||||
|
||||
- **Don't set `MASTRA_API_TOKEN` in the env for project/deploy commands** — it makes the CLI report `No organizations found`. Rely on the interactive login session instead.
|
||||
- If you keep multiple env files (e.g. `.env.deploy` and `.env.local`), `studio deploy` errors with `Multiple env files found`; pass `--env-file <file>` to disambiguate.
|
||||
|
||||
## 5. Pass the creds via `neon.ts` (third-party env)
|
||||
|
||||
Neon-injected vars (`DATABASE_URL`, `OPENAI_*`, AI Gateway) are automatic. Declare only third-party vars under the function's `env`, resolved from `process.env` at deploy time:
|
||||
|
||||
```typescript
|
||||
// neon.ts
|
||||
functions: {
|
||||
myapp: {
|
||||
name: "my app",
|
||||
source: "src/index.ts",
|
||||
env: {
|
||||
MASTRA_PROJECT_ID: process.env.MASTRA_PROJECT_ID ?? "",
|
||||
MASTRA_PLATFORM_ACCESS_TOKEN: process.env.MASTRA_PLATFORM_ACCESS_TOKEN ?? "",
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
Load the values from a git-ignored file at deploy time:
|
||||
|
||||
```bash
|
||||
neon deploy --env .env.deploy
|
||||
```
|
||||
|
||||
## 6. Verify
|
||||
|
||||
Send a request that exercises the agent, then open the Mastra Studio project's **Observability / Traces** view — you'll see the agent run (model calls, latency, token usage) under the `serviceName` you configured. Only `SPAN_ENDED` events are exported, buffered and flushed periodically, so a trace appears a few seconds after the agent run completes.
|
||||
|
||||
## Further reading
|
||||
|
||||
- https://mastra.ai/docs/observability/tracing/exporters/cloud
|
||||
- https://mastra.ai/reference/observability/tracing/exporters/mastra-platform-exporter
|
||||
- https://mastra.ai/docs/agents/structured-output
|
||||
- Neon AI Gateway dialects: the `neon-ai-gateway` skill
|
||||
@@ -0,0 +1,137 @@
|
||||
# MCP servers on Neon Functions
|
||||
|
||||
A [Model Context Protocol](https://modelcontextprotocol.io) server is a textbook Neon Functions workload: it's a long-running HTTP handler that an AI client (Cursor, Claude, ChatGPT, an agent) calls to discover and invoke tools, and those tools usually read and write a database. Running it as a Neon Function puts the MCP server's compute next to its Postgres data, gives it a public HTTPS URL, and lets it branch with the rest of your backend — each branch gets its own MCP server against its own isolated data.
|
||||
|
||||
MCP's **streamable HTTP transport** is a plain `POST`/`GET` on a single endpoint (conventionally `/mcp`), so it maps directly onto a function's web-standard `fetch` handler — no `upgrade` method or extra protocol like [WebSockets](../SKILL.md#websocket-servers) needed. A Hono app is the simplest host.
|
||||
|
||||
## The server
|
||||
|
||||
Two packages do the work: the official [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-sdk) (defines the server and its tools) and [`@hono/mcp`](https://github.com/honojs/middleware/tree/main/packages/mcp) (bridges MCP's streamable HTTP transport to a Hono route). Tools query Postgres through Drizzle on a module-scope `pg` pool, exactly like any other function (see [Connecting to Postgres](../SKILL.md#connecting-to-postgres)).
|
||||
|
||||
```typescript
|
||||
// src/index.ts
|
||||
import { Hono } from "hono";
|
||||
import { drizzle } from "drizzle-orm/node-postgres";
|
||||
import { Pool } from "pg";
|
||||
import { eq } from "drizzle-orm";
|
||||
import { z } from "zod";
|
||||
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||
import { StreamableHTTPTransport } from "@hono/mcp";
|
||||
import { contacts } from "./db/schema";
|
||||
|
||||
// One pool per isolate, reused across requests.
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
|
||||
const db = drizzle(pool);
|
||||
|
||||
const mcpServer = new McpServer({ name: "contacts", version: "1.0.0" });
|
||||
|
||||
// Each tool: a name, a config (description + a Zod input schema), and a handler
|
||||
// that returns MCP content. The Zod shape becomes the tool's JSON schema, which
|
||||
// the client uses to call the tool correctly.
|
||||
mcpServer.registerTool(
|
||||
"create_contact",
|
||||
{
|
||||
title: "Create contact",
|
||||
description: "Create a new contact.",
|
||||
inputSchema: {
|
||||
name: z.string().describe("Full name (required)."),
|
||||
email: z.string().optional().describe("Email address."),
|
||||
},
|
||||
},
|
||||
async ({ name, email }) => {
|
||||
const [row] = await db.insert(contacts).values({ name, email }).returning();
|
||||
return { content: [{ type: "text", text: JSON.stringify(row) }] };
|
||||
},
|
||||
);
|
||||
|
||||
mcpServer.registerTool(
|
||||
"delete_contact",
|
||||
{
|
||||
title: "Delete contact",
|
||||
description: "Delete a contact by id.",
|
||||
inputSchema: { id: z.number().int().positive() },
|
||||
},
|
||||
async ({ id }) => {
|
||||
const [row] = await db.delete(contacts).where(eq(contacts.id, id)).returning();
|
||||
return { content: [{ type: "text", text: JSON.stringify(row ?? { error: "not found" }) }] };
|
||||
},
|
||||
);
|
||||
|
||||
// Connect the server to the transport once per isolate, then let the Hono route
|
||||
// hand every /mcp request (POST for calls, GET for the stream) to the transport.
|
||||
const transport = new StreamableHTTPTransport();
|
||||
const app = new Hono();
|
||||
|
||||
app.all("/mcp", async (c) => {
|
||||
if (!mcpServer.isConnected()) await mcpServer.connect(transport);
|
||||
return transport.handleRequest(c);
|
||||
});
|
||||
|
||||
export default app;
|
||||
```
|
||||
|
||||
Key points:
|
||||
|
||||
- **Module scope.** Build the `McpServer`, register its tools, create the `StreamableHTTPTransport`, and open the `pg` pool once at module load — they're reused across every request the isolate serves (see [runtime limits](../SKILL.md#timeouts-and-runtime-limits)). Connect the transport lazily with the `isConnected()` guard so it happens once.
|
||||
- **State in Postgres.** Module memory doesn't survive isolate eviction, and several isolates run in parallel — so the source of truth for anything a tool reads or writes belongs in Postgres, not an in-memory structure.
|
||||
- **The URL.** After `neon deploy`, the server lives at `https://<branch_id>-<slug>.compute.…neon.tech/mcp`. Point any streamable-HTTP MCP client at that `/mcp` path.
|
||||
|
||||
## Authenticating the server
|
||||
|
||||
> [!WARNING]
|
||||
> A Neon Function has a **public HTTPS URL — anyone can reach it.** An unauthenticated MCP server hands every caller your tools (and the database behind them). Authenticate at the top of the handler before touching the transport, exactly as for [any client-facing function](../SKILL.md#functions-as-an-agent-backend-nextjs-and-similar-frameworks).
|
||||
|
||||
[Better Auth](https://better-auth.com) (self-hostable, runs alongside your app) is a good fit, and it covers both common shapes. **Better Auth is evolving quickly** — the MCP plugin is moving out of `better-auth/plugins` into its own `@better-auth/mcp` package (built on the OAuth Provider plugin), which renames `withMcpAuth` → `requireMcpAuth` and `createMcpAuthClient` → `createMcpResourceClient`. Verify the current package and import paths against the [Better Auth MCP docs](https://better-auth.com/docs/plugins/mcp) before wiring it up.
|
||||
|
||||
### Option 1 — OAuth via the Better Auth MCP plugin (best for third-party clients)
|
||||
|
||||
The [MCP plugin](https://better-auth.com/docs/plugins/mcp) makes your **Better Auth app the OAuth authorization server** for MCP, implementing the MCP authorization spec end to end: discovery (`/.well-known/oauth-authorization-server`, `/.well-known/oauth-protected-resource`), dynamic client registration, and the consent/token flow. MCP clients that support OAuth (Cursor, Claude, ChatGPT) then sign the user in and obtain a token with no API key to copy around.
|
||||
|
||||
Your Neon Function is the **resource server** — a separate service from the Better Auth app, so it doesn't share a process. Use Better Auth's **remote MCP client** to validate the incoming Bearer token against the auth server's published JWKS, and serve the protected-resource metadata so clients can discover where to authenticate:
|
||||
|
||||
```typescript
|
||||
// src/index.ts (sketch) — verify the bearer token against your remote Better Auth server.
|
||||
// Import path/name depend on your Better Auth version (createMcpAuthClient in better-auth/plugins/mcp/client,
|
||||
// or createMcpResourceClient in @better-auth/mcp/client) — check the docs.
|
||||
import { createMcpAuthClient } from "better-auth/plugins/mcp/client";
|
||||
|
||||
const mcpAuth = createMcpAuthClient({ authURL: process.env.AUTH_URL }); // your Better Auth base URL
|
||||
|
||||
app.all("/mcp", async (c) => {
|
||||
const session = await mcpAuth.verify?.(c.req.raw); // verifies the Bearer token via the remote JWKS
|
||||
if (!session) {
|
||||
// Tell the client where to authenticate (RFC 9728 / MCP spec).
|
||||
return c.json({ error: "unauthorized" }, 401, {
|
||||
"WWW-Authenticate": `Bearer resource_metadata="${process.env.AUTH_URL}/.well-known/oauth-protected-resource"`,
|
||||
});
|
||||
}
|
||||
if (!mcpServer.isConnected()) await mcpServer.connect(transport);
|
||||
return transport.handleRequest(c); // scope tools to session.userId
|
||||
});
|
||||
```
|
||||
|
||||
Pass `AUTH_URL` (and any signing/JWKS config) to the function via its `env` in `neon.ts` (see [Environment variables](../SKILL.md#environment-variables)). Because the function only verifies tokens against the remote server, the Better Auth instance can live anywhere — typically your Next.js / app host on Vercel.
|
||||
|
||||
### Option 2 — API key or session JWT via self-hosted Better Auth (simplest)
|
||||
|
||||
When the callers are your own agents/services or a personal MCP server, you don't need the full OAuth dance. Run Better Auth self-hosted and either:
|
||||
|
||||
- **API keys** — enable Better Auth's [API Key plugin](https://better-auth.com/docs/plugins/api-key), issue a key, and have the function verify the `Authorization: Bearer <key>` (or an `x-api-key` header) on every request; or
|
||||
- **Session JWT** — mint a short-lived JWT with Better Auth's `jwt` plugin and verify it in the function against the app's JWKS, the same `jose` pattern used for the [agent backend](../SKILL.md#functions-as-an-agent-backend-nextjs-and-similar-frameworks).
|
||||
|
||||
Either way it's one check at the top of the `/mcp` route — reject anything that doesn't carry a valid key/token before connecting the transport:
|
||||
|
||||
```typescript
|
||||
app.all("/mcp", async (c) => {
|
||||
const auth = c.req.header("authorization");
|
||||
if (!(await isValidApiKey(auth))) return c.json({ error: "unauthorized" }, 401); // your check
|
||||
if (!mcpServer.isConnected()) await mcpServer.connect(transport);
|
||||
return transport.handleRequest(c);
|
||||
});
|
||||
```
|
||||
|
||||
This keeps the secret server-side, costs nothing to operate, and is trivial to rotate — a solid default until you need third-party clients to self-authorize, at which point reach for Option 1.
|
||||
|
||||
## Testing
|
||||
|
||||
Drive the server with any MCP client. [`mcporter`](https://github.com/instructa/mcporter) is a quick CLI for it — `mcporter list <url>/mcp --schema` lists the tools and `mcporter call "<url>/mcp.<tool>" key=value` invokes one (`--allow-http` for a local `neon dev` URL). To wire it into a client interactively, `npx add-mcp <url>/mcp -a <agent>` writes the client config for you.
|
||||
@@ -0,0 +1,131 @@
|
||||
# Integrations and observability
|
||||
|
||||
A Neon Function is a **long-lived Node.js 24 process running a web-standard request/response handler** — not an edge worker or a short-lived lambda. That means any integration SDK that works in an ordinary Node process works here unchanged: you initialize it once at module load, before your handler starts serving requests, and it stays instrumented for the life of the isolate.
|
||||
|
||||
This reference walks through wiring up Sentry for error and performance monitoring; the same shape (init module imported first, gated on an env var, secret passed at deploy time) applies to other Node SDKs (OpenTelemetry, logging, analytics).
|
||||
|
||||
## Sentry (error & performance monitoring)
|
||||
|
||||
Because the runtime is a normal Node process, use the Node SDK `@sentry/node` — not an edge/serverless wrapper. It bundles cleanly through `neon deploy`'s esbuild with no extra build config.
|
||||
|
||||
There are three layers worth instrumenting, and errors from all of them flow into a single Sentry project:
|
||||
|
||||
1. The HTTP framework (unhandled route errors).
|
||||
2. The Node function runtime (uncaught exceptions / unhandled rejections, captured by the SDK).
|
||||
3. The application's own caught failures — e.g. an agent that retries and falls back instead of throwing.
|
||||
|
||||
### 1. Initialize before anything else
|
||||
|
||||
Put `Sentry.init` in its own module and import it as the very first import of your entry file, so the process is instrumented before any other code (your handler, the DB pool, the agent) loads.
|
||||
|
||||
```typescript
|
||||
// src/instrument.ts
|
||||
import * as Sentry from "@sentry/node";
|
||||
|
||||
Sentry.init({
|
||||
dsn: process.env.SENTRY_DSN,
|
||||
enabled: Boolean(process.env.SENTRY_DSN),
|
||||
tracesSampleRate: 1.0,
|
||||
// NEON_BRANCH (the branch name) is injected on EVERY branch, including the default — so it
|
||||
// can't be used as a truthy "is this a branch?" flag. Treat the project's default branch as
|
||||
// "production" (its name passed in via neon.ts env) and tag every other branch by its name.
|
||||
environment:
|
||||
process.env.NEON_BRANCH && process.env.NEON_BRANCH !== process.env.PRODUCTION_BRANCH
|
||||
? process.env.NEON_BRANCH
|
||||
: "production",
|
||||
});
|
||||
|
||||
export { Sentry };
|
||||
```
|
||||
|
||||
```typescript
|
||||
// src/index.ts
|
||||
import "./instrument"; // MUST be the first import, before the framework/agent
|
||||
import { Sentry } from "./instrument";
|
||||
import { Hono } from "hono";
|
||||
// ... rest of the function
|
||||
```
|
||||
|
||||
- **Gate `enabled` on the DSN.** Local dev (`neon dev`) and any branch where you haven't configured the secret then become a no-op — no init, no noise — without changing code.
|
||||
- **Tag the environment off the injected branch name.** Each Neon branch runs its own copy of the function and the runtime injects `NEON_BRANCH` (the branch **name**, e.g. `main` or `preview/add-auth`) into every one of them — including the default branch. The same value is written into local dev by `neon env pull` / `neon-env run` / `neon dev`, so local and deployed runs agree. Because it's always present, don't use it as a boolean flag (that tags every branch the same). Instead compare it against your default branch name (pass it in as e.g. `PRODUCTION_BRANCH` via `neon.ts` `env`) so the default branch reads as `production` and feature/preview branches are tagged by name — keeping them separable in the Sentry dashboard.
|
||||
|
||||
### 2. Provide the DSN as a deploy-time secret
|
||||
|
||||
The DSN is your own secret, so set it per-deployment (see "Environment variables" in `SKILL.md`). Either pass it on deploy:
|
||||
|
||||
```bash
|
||||
neon functions deploy <slug> --src src/index.ts \
|
||||
--env "SENTRY_DSN=https://…@…ingest.us.sentry.io/…"
|
||||
```
|
||||
|
||||
or declare it under the function's `env` in `neon.ts` (read from `process.env` to avoid hardcoding):
|
||||
|
||||
```typescript
|
||||
functions: {
|
||||
<slug>: {
|
||||
name: "…",
|
||||
source: "src/index.ts",
|
||||
env: { SENTRY_DSN: process.env.SENTRY_DSN! },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Catch unhandled route errors
|
||||
|
||||
Wire a top-level error handler in your HTTP framework so any error thrown in a route is reported. With Hono, `onError` covers this. Watch out for one gotcha: framework middleware such as `cors()` usually does **not** decorate error responses, so re-add any headers you need on the 500 yourself.
|
||||
|
||||
```typescript
|
||||
app.onError((err, c) => {
|
||||
Sentry.captureException(err);
|
||||
c.header("access-control-allow-origin", "*"); // cors() doesn't run on error responses
|
||||
return c.json({ error: "internal_error" }, 500);
|
||||
});
|
||||
```
|
||||
|
||||
### 4. Report agent (and other swallowed) failures explicitly
|
||||
|
||||
Long-running agent workloads — the case Neon Functions are built for — typically **catch their own errors and fall back** (retry a different model, return a degraded result) rather than throwing. Those failures never reach the route error handler, so report them explicitly with the same `Sentry` instance, and tag them so you can filter and group in the dashboard.
|
||||
|
||||
A representative agent that parses a page across several models reports three distinct cases:
|
||||
|
||||
```typescript
|
||||
// Recoverable: one model attempt failed, the agent will try the next model.
|
||||
Sentry.captureException(err, {
|
||||
level: "warning",
|
||||
tags: { component: "agent", phase: "parse-attempt", model },
|
||||
extra: { url, source },
|
||||
});
|
||||
|
||||
// Terminal: every model failed.
|
||||
Sentry.captureException(err, {
|
||||
level: "error",
|
||||
tags: { component: "agent", phase: "parse-all-failed" },
|
||||
extra: { url, source },
|
||||
});
|
||||
|
||||
// Non-exception failure: the agent couldn't fetch the input page at all.
|
||||
Sentry.captureMessage("agent could not fetch page", {
|
||||
level: "warning",
|
||||
tags: { component: "agent", phase: "fetch" },
|
||||
extra: { url, source },
|
||||
});
|
||||
```
|
||||
|
||||
- Use `level` to separate recoverable (`warning`) from terminal (`error`) failures.
|
||||
- Use `tags` for the dimensions you'll filter/group by — `component`, `phase`, `model`.
|
||||
- Use `extra` for per-event context — the URL being processed, the content source.
|
||||
|
||||
### Verifying the wiring
|
||||
|
||||
- Temporarily add a route that throws (`app.get("/debug-sentry", () => { throw new Error("sentry test"); })`), hit it, confirm the 500 surfaces in Sentry, then remove the route.
|
||||
- Trigger a real downstream failure (e.g. point a fetch at `https://httpstat.us/500`) to confirm the explicit agent-level captures fire.
|
||||
|
||||
## Other Node integrations
|
||||
|
||||
The same pattern generalizes to any Node integration (OpenTelemetry, structured logging, product analytics):
|
||||
|
||||
1. Initialize once at module scope in a dedicated init module, imported before your handler.
|
||||
2. Gate it on an env var so local dev and unconfigured branches are a no-op.
|
||||
3. Pass secrets via `--env KEY=VALUE` on deploy or the function's `env` in `neon.ts`.
|
||||
|
||||
Standard Node SDKs bundle through `neon deploy`'s esbuild without changes.
|
||||
@@ -0,0 +1,143 @@
|
||||
# Server-sent events (SSE) on Neon Functions
|
||||
|
||||
SSE is the one-way (server → client) streaming counterpart to WebSockets: the browser opens a long-lived `GET` with [`EventSource`](https://developer.mozilla.org/en-US/docs/Web/API/EventSource) and the server pushes text frames down it. On Neon Functions there's **no adapter or extra library to install** — unlike the [Hono WebSocket helper](hono-websockets.md), an SSE endpoint is just a normal `fetch` handler that returns a `Response` whose body is a `ReadableStream` with `Content-Type: text/event-stream`. The runtime holds the response open as long as bytes keep flowing (15-minute heartbeat, see [Timeouts](../SKILL.md#timeouts-and-runtime-limits)).
|
||||
|
||||
Reach for SSE over WebSockets when you only need server → client updates (live counters, notifications, progress, token streams) — it's simpler to run (plain HTTP, no `upgrade`), and `EventSource` **reconnects on its own**, so there's no client backoff to write.
|
||||
|
||||
## Minimal SSE endpoint (no framework)
|
||||
|
||||
A function's default export is `{ fetch }`; SSE needs nothing more. Return a `ReadableStream` and write `data:` frames into it:
|
||||
|
||||
```typescript
|
||||
// src/index.ts
|
||||
const encoder = new TextEncoder();
|
||||
|
||||
export default {
|
||||
fetch(request: Request): Response {
|
||||
const url = new URL(request.url);
|
||||
if (url.pathname !== "/events") return new Response("ok");
|
||||
|
||||
const stream = new ReadableStream<Uint8Array>({
|
||||
start(controller) {
|
||||
// An SSE frame is `data: <payload>\n\n`. A line starting with `:` is a
|
||||
// comment — used here as a heartbeat to keep the stream from going idle.
|
||||
controller.enqueue(encoder.encode("data: hello\n\n"));
|
||||
const timer = setInterval(
|
||||
() => controller.enqueue(encoder.encode(": ping\n\n")),
|
||||
25_000,
|
||||
);
|
||||
// cancel() fires when the client disconnects.
|
||||
return () => clearInterval(timer);
|
||||
},
|
||||
});
|
||||
|
||||
return new Response(stream, {
|
||||
headers: {
|
||||
"Content-Type": "text/event-stream",
|
||||
"Cache-Control": "no-cache, no-transform",
|
||||
Connection: "keep-alive",
|
||||
},
|
||||
});
|
||||
},
|
||||
};
|
||||
```
|
||||
|
||||
> `cancel()` is returned from `start()` here for brevity; you can also declare it as a separate `cancel()` method on the stream's underlying source. Either way, use it to drop the client from any broadcast set and clear timers.
|
||||
|
||||
## With Hono
|
||||
|
||||
Hono routes the HTTP side; the SSE response is the same `ReadableStream`. Returning a raw `Response` keeps full control over the stream (and sidesteps concurrent-write edge cases in stream helpers):
|
||||
|
||||
```typescript
|
||||
// src/index.ts
|
||||
import { Hono } from "hono";
|
||||
import { cors } from "hono/cors";
|
||||
|
||||
const app = new Hono();
|
||||
app.use("*", cors({ origin: process.env.WEB_ORIGIN ?? "*" })); // EventSource is cross-origin from a SPA
|
||||
|
||||
app.get("/events", (c) => {
|
||||
const stream = new ReadableStream<Uint8Array>({
|
||||
start(controller) {
|
||||
controller.enqueue(new TextEncoder().encode("data: connected\n\n"));
|
||||
// ...register `controller` in a broadcast set; see fan-out below.
|
||||
},
|
||||
});
|
||||
return new Response(stream, {
|
||||
headers: { "Content-Type": "text/event-stream", "Cache-Control": "no-cache, no-transform" },
|
||||
});
|
||||
});
|
||||
|
||||
export default app;
|
||||
```
|
||||
|
||||
## Push to every client, across isolates
|
||||
|
||||
The fan-out rule is identical to WebSockets ([Fan-out across isolates](../SKILL.md#fan-out-across-isolates-do-not-skip-this)): each isolate keeps its **own** set of open streams, so broadcasting in-process only reaches the clients on that isolate. Hold a `Set` of stream controllers, and fan out across isolates with Postgres `LISTEN`/`NOTIFY`. Keep the source-of-truth state in Postgres — module state doesn't survive eviction.
|
||||
|
||||
```typescript
|
||||
import { Pool, Client } from "pg";
|
||||
|
||||
const encoder = new TextEncoder();
|
||||
const clients = new Set<ReadableStreamDefaultController<Uint8Array>>();
|
||||
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
|
||||
const CHANNEL = "events";
|
||||
|
||||
// One dedicated DIRECT connection per isolate to receive events (LISTEN needs a
|
||||
// real session — use DATABASE_URL_UNPOOLED, not the pooled URL).
|
||||
const listener = new Client({ connectionString: process.env.DATABASE_URL_UNPOOLED });
|
||||
listener.connect().then(() => listener.query(`LISTEN ${CHANNEL}`));
|
||||
listener.on("notification", (msg) => {
|
||||
if (!msg.payload) return;
|
||||
const frame = encoder.encode(`data: ${msg.payload}\n\n`);
|
||||
for (const controller of clients) {
|
||||
try {
|
||||
controller.enqueue(frame); // enqueue is synchronous — no concurrent-await hazard
|
||||
} catch {
|
||||
clients.delete(controller); // controller already closed
|
||||
}
|
||||
}
|
||||
});
|
||||
|
||||
// Anywhere you mutate state, NOTIFY so every isolate pushes to its own streams.
|
||||
function publish(payload: unknown) {
|
||||
return pool.query("SELECT pg_notify($1, $2)", [CHANNEL, JSON.stringify(payload)]);
|
||||
}
|
||||
```
|
||||
|
||||
Register/unregister each connection in `clients` from the stream's `start`/`cancel`, and add a module-scope heartbeat (`setInterval`, every ~25–30s) that enqueues `: ping\n\n` to every controller so idle streams stay alive (see [Caveats](#caveats)).
|
||||
|
||||
## Wire format (just text)
|
||||
|
||||
Each event is newline-delimited fields ending in a blank line:
|
||||
|
||||
```
|
||||
data: a one-line payload\n\n
|
||||
event: count\ndata: 42\n\n # named event → addEventListener("count", …)
|
||||
id: 7\ndata: resumable\n\n # sets EventSource.lastEventId for resume
|
||||
: this is a comment / heartbeat\n\n # ignored by the client; keeps the stream warm
|
||||
retry: 5000\n\n # tells the client how long to wait before reconnecting
|
||||
```
|
||||
|
||||
Send `data:` with no `event:` field to deliver the default `message` event, which the client reads with `EventSource.onmessage` (no `addEventListener` needed).
|
||||
|
||||
## Client
|
||||
|
||||
```typescript
|
||||
const source = new EventSource(`${FUNCTION_URL}/events`); // GET only
|
||||
source.onmessage = (e) => console.log("update", e.data); // default "message" events
|
||||
source.onerror = () => {/* EventSource auto-reconnects; nothing to do */};
|
||||
// source.close() to stop.
|
||||
```
|
||||
|
||||
`EventSource` **reconnects automatically** with the server's `retry:` interval, replaying `Last-Event-ID` if you set `id:` — so unlike WebSockets you don't write a reconnect loop. Its constraints: it's **GET-only and can't set request headers**, so authenticate the same way as a [WebSocket](../SKILL.md#websocket-servers) — a `?token=` query param (verify with `jwtVerify` before streaming) or a cookie. (Use the modern `eventsource` polyfill if you need `Authorization` headers.)
|
||||
|
||||
## Caveats
|
||||
|
||||
- **Heartbeat or it dies.** Streams stay open only while bytes flow — Neon's window is 15 min ([Timeouts](../SKILL.md#timeouts-and-runtime-limits)), but intermediary proxies are usually far stricter (tens of seconds). Emit a `: ping\n\n` comment every ~25–30s so the stream never goes quiet.
|
||||
- **`no-transform`.** Set `Cache-Control: no-cache, no-transform` so proxies don't buffer or rewrite the stream.
|
||||
- **Enqueue is synchronous.** `controller.enqueue()` doesn't return a promise, so broadcasting from the `LISTEN` handler can't interleave awaits mid-write — wrap each in `try/catch` and drop dead controllers.
|
||||
- **CORS.** A SPA hits the function cross-origin, so set `Access-Control-Allow-Origin`. `EventSource` sends no credentials by default, so `*` is fine for public streams.
|
||||
- **One-way only.** SSE is server → client. For client → server, the browser makes normal `fetch`/`POST` calls (often to the same function); reach for [WebSockets](../SKILL.md#websocket-servers) only when you need bidirectional, low-latency frames.
|
||||
|
||||
Together — a Hono `fetch` SSE endpoint, `LISTEN`/`NOTIFY` fan-out, heartbeat, a counter persisted in Postgres, and a client-only TanStack Router SPA consuming it with `EventSource` — these compose into a complete realtime backend on a single function.
|
||||
Reference in New Issue
Block a user