SKILL.md · 24000
ng](references/production-hardening.md).
Building the agent itself. The Vercel AI SDK and Mastra are the recommended ways to build the agent — point either at the Neon AI Gateway (see the neon-ai-gateway skill) for one credential across every model, with no extra provider keys. For a complete AI SDK agent running as a Function (streaming toUIMessageStreamResponse, multi-step tool calling next to Postgres, and persisting generated images to Object Storage), see references/ai-sdk.md; for the Mastra equivalent with built-in tracing, see references/mastra-studio.md.
The fix: call the function directly from the client. Don't route the long request through your app server.
Browser ──(Authorization: Bearer <JWT>)──▶ Neon Function (agent) ✅ no host timeout
Browser ──▶ your app backend ──▶ Neon Function ❌ host cuts the stream
- Get a short-lived bearer token from the identity the app already uses. Do not switch Clerk, Better Auth, Auth.js, Supabase Auth, or Managed Auth in order to call a Function.
- Managed Auth, default client (
createAuthClient/ Next wrapper):authClient.token(), thendata.token. Verify with injectedNEON_AUTH_JWKS_URLand issuernew URL(process.env.NEON_AUTH_BASE_URL!).origin. - Managed Auth with
SupabaseAuthAdapter(): that client has no.token(). UsegetSession(), thendata.session.access_token. Same JWKS/issuer as above. - Existing Better Auth / Auth.js / other signer that already publishes JWKS: use that JWKS URL, issuer, and audience. Inspect the installed contract; cookie or database sessions are not a JWKS.
- Cookie/database sessions only: mint a short token on the existing app backend (that call is fast and stays within host limits), then the browser calls the Function directly with
Authorization: Bearer. The Function stream must not go through the app host.
- Managed Auth, default client (
- Hand the token to the client, e.g. with the Vercel AI SDK:
new DefaultChatTransport({ api: NEON_FUNCTION_URL, fetch })wherefetchattachesAuthorization: Bearer <token>. Your app server is never in the path of the long stream. - Add CORS so the browser can reach it (handle
OPTIONS, setAccess-Control-Allow-Origin/-Headers).
[!WARNING] A Neon Function has a public HTTPS URL — it is reachable by anyone. A direct client→function call means there is no app backend in front of it to gate access, so you must authenticate the function yourself. Verify a JWT against the caller's JWKS, check a shared secret / API key, or reject the request. Never deploy an unauthenticated agent. Browser callers use short-lived user tokens. Server or proxy origin secrets (
X-Secret) stay server-side; see Production hardening.
// src/index.ts — verify the caller before doing any work
import { createRemoteJWKSet, jwtVerify } from "jose";
const jwks = createRemoteJWKSet(new URL(process.env.NEON_AUTH_JWKS_URL!));
const issuer = new URL(process.env.NEON_AUTH_BASE_URL!).origin;
export default {
async fetch(request: Request) {
if (request.method === "OPTIONS")
return new Response(null, { status: 204, headers: cors(request) });
const auth = request.headers.get("authorization");
if (!auth?.toLowerCase().startsWith("bearer ")) {
return new Response("Unauthorized", {
status: 401,
headers: cors(request),
});
}
let userId: string;
try {
const { payload } = await jwtVerify(auth.slice(7), jwks, { issuer });
if (!payload.sub) {
return new Response("Unauthorized", {
status: 401,
headers: cors(request),
});
}
userId = payload.sub;
} catch {
return new Response("Unauthorized", {
status: 401,
headers: cors(request),
});
}
// Authorize resource access by userId, then run the agent scoped to that user.
// ... return result.toUIMessageStreamResponse({ headers: cors(request) })
},
};
That snippet is Managed Auth verification. Mint the bearer token with .token() (data.token) on the default client, or getSession() then data.session.access_token on SupabaseAuthAdapter(). For another identity, pass that app's JWKS URL and issuer through Function env (see Environment Variables) and include audience only when that token contract requires it. https://neon.com/docs/compute/functions/authentication.md
A valid token is not permission to read another user's rows. Exercise two users: each can access their own data; cross-user access is denied. Repeat after restarting the Function against stored rows. A request-supplied owner id cannot grant access.
Persist anything you need to keep (generated images, history) in Postgres — module state doesn't survive eviction.
WebSocket Servers
A WebSocket server is the canonical Functions workload: a long-running handler holds connections open in-process, with no external state store needed to keep a stream coherent. The connection stays alive as long as bytes flow (15-minute heartbeat, see Timeouts).
Upgrade from inside fetch. Call upgradeWebSocket(request) from @neon/functions and return the response it gives you. Hono apps use the same primitive via @neon/functions/hono (see Hono below). There is one entrypoint and no WebSocket dependency to install:
import { upgradeWebSocket } from "@neon/functions";
export default {
async fetch(req: Request): Promise<Response> {
if (req.headers.get("upgrade")?.toLowerCase() !== "websocket") {
return new Response("expected a websocket upgrade", { status: 426 });
}
const { socket, response } = upgradeWebSocket(req);
socket.addEventListener("message", (event) => socket.send(event.data));
return response;
},
};
socket is a standard WebSocket, so addEventListener and the onopen/onmessage/onclose/onerror properties both work. It is still CONNECTING when you get it — the runtime writes the 101 only once your handler returns response, and the socket opens then.
Three rules that matter:
- Return
responseunchanged. A101can't be built as a plainResponse(the fetch spec caps constructed responses at 200–599), so the runtime hands back an object carrying the pending upgrade.clone(), or rebuilding it withnew Response(res.body, res)as response-rewriting middleware does, discards the upgrade and fails the request. - Refuse a handshake by returning an ordinary
Response. Return a401,403, or404fromfetch, before you upgrade, to gate a socket. A browser client can't read why a handshake was refused; it sees only a generic connection failure, not your status or body. Refuse to keep clients out, but send any detail the client needs over a separate authenticated request. binaryTypedefaults to"arraybuffer", not the browser's"blob".event.datais astringfor text frames and anArrayBufferfor binary ones, so branch ontypeof.
With auth. Browsers can't set headers on a WebSocket, so authenticate with a ?token= query param (verify it the same way as the agent backend: jwtVerify against your JWKS) and refuse before upgrading:
// src/index.ts
import { upgradeWebSocket } from "@neon/functions";
const clients = new Set<WebSocket>();
export default {
async fetch(request: Request): Promise<Response> {
if (request.headers.get("upgrade")?.toLowerCase() !== "websocket") {
return new Response("WebSocket endpoint — connect with ?token=<jwt>");
}
const url = new URL(request.url);
const identity = await verifyToken(url.searchParams.get("token"));
if (!identity) return new Response("unauthorized", { status: 401 });
const { socket, response } = upgradeWebSocket(request);
clients.add(socket);
socket.addEventListener("close", () => clients.delete(socket));
socket.addEventListener("message", (event) => {
if (typeof event.data !== "string") return;
persist(identity.id, event.data); // fan out to every isolate — see below
});
return response;
},
};
Subprotocols. Pass { protocol } to select one the client offered; it is echoed in Sec-WebSocket-Protocol and exposed as socket.protocol. Selecting one the client did not offer throws a TypeError. Omit it and no protocol is negotiated. No extensions are negotiated either — socket.extensions is always "" and permessage-deflate is not available.
Hono. Use upgradeWebSocket from @neon/functions/hono — the same primitive as Hono's own WebSocket helper, with no ws dependency and not the deprecated @hono/node-ws. Auth is ordinary middleware; gate upgrade requests before next():
// src/index.ts
import { Hono } from "hono";
import { upgradeWebSocket } from "@neon/functions/hono";
const clients = new Set<WebSocket>();
const app = new Hono<{ Variables: { userId: string } }>();
app.use("/ws", async (c, next) => {
const identity = await verifyToken(c.req.query("token"));
if (!identity) return c.text("Unauthorized", 401);
c.set("userId", identity.id);
await next();
});
app.get(
"/ws",
upgradeWebSocket((c) => ({
onOpen(_event, ws) {
clients.add(ws.raw);
ws.send("welcome");
},
onClose(_event, ws) {
clients.delete(ws.raw);
},
onMessage(event, ws) {
ws.send(`echo: ${event.data}`);
},
})),
);
export default app;
Connect from the browser with the function's wss:// URL (from neon functions get <slug>), for example new WebSocket("wss://<branch>-<slug>.compute.<region>.aws.neon.tech/ws?token=<jwt>"). Reconnect on close — isolates are evictable and idle connections may be terminated after 15 minutes.
Do not put cors() on the upgrade route, and do not read c.res before await next() or call c.header() after it — both rebuild the 101 and break the upgrade. See @neon/functions README for the full middleware table.
Heartbeat (keep the socket alive)
A connection stays open only while bytes flow: Neon evicts a silent stream after 15 minutes (Timeouts and Runtime Limits), and intermediary proxies / load balancers are usually far stricter (often tens of seconds). Don't rely on the app being chatty enough — send a periodic keepalive from the server so the socket never goes quiet.
The standard WebSocket interface has no ping(), so send an application-level message the client filters out:
const HEARTBEAT_MS = 25_000; // comfortably under proxy idle timeouts
const beat = setInterval(() => {
for (const socket of clients) {
if (socket.readyState === socket.OPEN) socket.send('{"type":"ping"}');
}
}, HEARTBEAT_MS);
beat.unref?.();
The client skips these when handling messages. There is no protocol-level shortcut here: the standard WebSocket from upgradeWebSocket has no ping(), and a browser can't send ping frames from JavaScript, so an application-level message is the only keepalive a browser client can use. (A Node ws client can send ping frames, and the server auto-replies with a pong, but a browser can't.)
Fan-out across isolates (do not skip this)
Under load the runtime runs several isolates in parallel, each with its own copy of module state — so each isolate has its own clients set. Broadcasting only to that local set means a client on isolate A never sees an event produced on isolate B, and the feed silently fractures. It's easy to miss: neon dev runs a single process (one isolate), so in-process broadcast always looks fine locally but breaks in production, where concurrent connections spread across many isolates.
If the data is database rows (live dashboards, feeds, chat over stored messages), use Neon Realtime (the neon-realtime skill) instead of hand-rolling fan-out. Using Realtime does not prevent your database from scaling to zero. The strategies below are for push that doesn't come from database rows (presence, typing, LLM streams), and the fallback where Realtime isn't available, such as on Claimable projects until they're claimed.
Module state doesn't survive eviction anyway, so Postgres is the shared source of truth. Pick a fan-out strategy. In every snippet below, pool is a pooled pg client and clients is this isolate's Set of live connections.
1. Poll Postgres — the default, and it keeps Scale to Zero. Each isolate re-reads the shared state (or rows past a cursor) on a short interval and pushes changes to its own clients. One query per isolate per tick (not per client), and none when the isolate has no clients — so an idle compute still suspends.
let lastId = "0"; // bigint id, so a string
let polling = false;
async function poll() {
if (polling || clients.size === 0) return; // guard overlap; no clients → no query → compute can scale to zero
polling = true;
try {
const { rows } = await pool.query(
"SELECT id, payload FROM events WHERE id > $1 ORDER BY id",
[lastId],
);
for (const { id, payload } of rows) {
lastId = id;
for (const socket of clients) {
if (socket.readyState === socket.OPEN) socket.send(payload);
}
}
} catch (err) {
console.error("[poll]", err);
} finally {
polling = false;
}
}
// Seed from the latest id so a fresh isolate sends only new rows, not the whole table, then poll.
pool
.query("SELECT coalesce(max(id), 0)::text AS id FROM events")
.then((seed) => {
lastId = seed.rows[0].id;
})
.catch((err) => console.error("[seed]", err))
.finally(() => setInterval(poll, 1000).unref?.());
- Latency: up to the interval (~1s).
- Scaling: database load grows with the number of live isolates, not clients. Keep the cursor on an indexed
serial/bigserialPK and the interval sane. - Scale to Zero: ✅ preserved — polling stops when no clients are connected, so the compute suspends on its normal timer.
- Ordering:
WHERE id > cursorcan skip a row that commits out of sequence: a transaction that took a lower id but commits after a higher one is already behind the cursor, so the poll never returns it. For a broadcast feed occasional loss is usually fine; when you need every row, useLISTEN/NOTIFYor poll bycreated_atwith a small overlap window and dedupe by id.
2. LISTEN/NOTIFY — lowest latency, but requires disabling Scale to Zero. Each isolate LISTENs on a channel over a dedicated unpooled connection; broadcasting is NOTIFY, so every isolate (including the sender's) re-pushes to its sockets. Near-instant — but the listener holds an idle connection that does not count as active, so Scale to Zero suspends the compute and drops it, silently killing the feed. Only use it on an always-on compute (Scale to Zero disabled — a paid-plan setting).
import { attachDatabasePool } from "@neon/functions";
import { Pool, Client } from "pg";
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 5 });
attachDatabasePool(pool);
const CHANNEL = "chat_events";
// One dedicated DIRECT connection per isolate, just to receive events.
// Use DATABASE_URL_UNPOOLED — LISTEN needs a real session, not a pooled one.
// Don't call attachDatabasePool here: it would silence the idle drop that killed the feed.
// The error listener keeps the process alive; reconnect the client on error in production (omitted here).
const listener = new Client({
connectionString: process.env.DATABASE_URL_UNPOOLED,
});
listener.on("error", (err) => {
console.error(err);
});
listener.connect().then(() => listener.query(`LISTEN ${CHANNEL}`));
listener.on("notification", (msg) => {
if (!msg.payload) return;
for (const socket of clients) {
if (socket.readyState === socket.OPEN) socket.send(msg.payload);
}
});
// Broadcast by NOTIFYing through the pool — every isolate's listener fires.
function broadcast(event: unknown) {
return pool.query("SELECT pg_notify($1, $2)", [
CHANNEL,
JSON.stringify(event),
]);
}
3. External pub/sub (e.g. Upstash Redis) — best at scale. For high fan-out, sub-second latency at large connection counts, or multi-region, publish/subscribe through a dedicated broker. Highest throughput, and it doesn't touch Postgres or block Scale to Zero — at the cost of another service to run.
Rule of thumb: for database rows, use Neon Realtime. Otherwise start with polling (works with Scale to Zero, no extra infra); switch to LISTEN/NOTIFY only on always-on compute that needs sub-second latency; move to Redis when fan-out outgrows Postgres.
Client must reconnect
Idle functions are evicted (and isolates restart for operational reasons), so a client's socket will drop — treat reconnection as normal, not exceptional. Reconnect with exponential backoff, capped, and re-mint a fresh token on every attempt (tokens are short-lived, so a stale one fails the upgrade auth check):
let closed = false,
retry = 0,
timer: ReturnType<typeof setTimeout>;
async function connect() {
if (closed) return;
const token = await getToken(); // re-mint each attempt; short-lived
const ws = new WebSocket(`${WS_URL}?token=${encodeURIComponent(token)}`);
ws.onopen = () => {
retry = 0; // reset backoff on success
};
ws.onmessage = (e) => {
/* apply the event */
};
ws.onclose = () => {
if (!closed)
timer = setTimeout(connect, Math.min(1000 * 2 ** retry++, 15000));
};
ws.onerror = () => ws.close(); // let onclose drive the retry
}
connect();
Together — upgradeWebSocket inside fetch, JWT auth over ?token=, cross-isolate fan-out, and client backoff — these compose into a complete WebSocket backend on a single function, for push that doesn't come from database rows (presence, typing, LLM streams) or where Realtime isn't available. For persisted chat, feeds, and other live UIs over database rows, use Neon Realtime (the neon-realtime skill).
Server-Sent Events (SSE)
When you only need server → client streaming (live counters, notifications, progress, token streams), SSE is simpler than a WebSocket and needs no upgrade at all: a plain fetch handler returns a Response whose body is a ReadableStream with Content-Type: text/event-stream, and the runtime holds it open as long as bytes flow. The browser consumes it with EventSource, which reconnects on its own — so there's no client backoff to write.
// src/index.ts — minimal SSE endpoint
const encoder = new TextEncoder();
export default {
fetch: () => {
let t: ReturnType<typeof setInterval>;
return new Response(
new ReadableStream<Uint8Array>({
start(controller) {
controller.enqueue(encoder.encode("data: hello\n\n"));
t = setInterval(
() => controller.enqueue(encoder.encode(": ping\n\n")),
25_000,
);
},
cancel() {
clearInterval(t); // fires when the client disconnects
},
}),
{
headers: {
"Content-Type": "text/event-stream",
"Cache-Control": "no-cache, no-transform",
},
},
);
},
};
The same rules as WebSockets apply. Heartbeat: a stream stays open only while bytes flow — Neon's window is 15 minutes (Timeouts and Runtime Limits) but proxies are usually far stricter, so emit a : ping\n\n comment every ~25–30s (shown above) to keep idle streams from being dropped. Keep state in Postgres, and fan out across isolates using one of the fan-out strategies (hold a Set of stream controllers and enqueue to each). EventSource is GET-only and can't set headers, so authenticate with a ?token= query param or cookie, exactly like the WebSocket case. references/sse.md has the full pattern — Hono variant, cross-isolate fan-out, wire format, client, and caveats.
Function Triggers
A Function Trigger POSTs JSON to your function on a cron (schedule) or when an object is created in Object Storage (storage_object_created). Declare it in neon.ts, apply with neon deploy, and authenticate the delivery with parseTriggerDelivery (@neon/functions/triggers). parseTrigger (Hono) and parseTriggerInvocation stay schedule-only. Prefer neon.ts; CLI and the Neon MCP trigger tools (list_triggers, create_trigger, …) are the backup.
Trigger routes must not require a user JWT or X-Secret; Neon POSTs to the native URL without those. Production caller shapes: references/production-hardening.md. Full field list, CLI, MCP, payload, inheritance, and both handler shapes: references/function-triggers.md.
MCP Servers
An MCP server is a natural Functions workload: a long-running HTTP handler that exposes tools to AI clients (Cursor, Claude, ChatGPT, agents), with those tools reading and writing the branch's Postgres right next to the compute. MCP's streamable HTTP transport is a plain POST/GET on a single endpoint (conventionally /mcp), so it maps onto a function's fetch handler with no upgrade method or extra protocol.
The simplest host is a Hono app using the official @modelcontextprotocol/sdk plus @hono/mcp, which bridges the transport to a route. Build the server, register its tools, and create the transport once at module scope, then hand every /mcp request to it:
const transport = new StreamableHTTPTransport();
app.all("/mcp", async (c) => {
if (!mcpServer.isConnected()) await mcpServer.connect(transport);
return transport.handleRequest(c);
});
Because the function's URL is public, authenticate before connecting the transport — Managed Better Auth is the OAuth server for third-party MCP clients (guard the Function with @neon/oauth; see the neon-auth skill's oauth-server.md), and a simpler API-key / session-JWT check covers your own callers. Public-consumer edge protection: references/production-hardening.md. references/mcp.md has the full pattern — server with Postgres-backed tools via Drizzle, the auth options, and testing with mcporter / add-mcp.
Integrations and Observability
Built-in branch logs
neon logs query --branch production --source function --since 1h
Functions is one of the two sources branch logs cover today, alongside Object Storage. Logs are scoped to a single branch, so pass --branch when the deployed function isn't on the branch you're checked out on. Everything else about logs — the required CLI version, filters, the SDK, and the Loki-compatible read API — is in the parent neon skill's Observability section.
Application instrumentation
A function is a long-lived Node.js process running a web-standard request/response handler, so standard Node integration SDKs work unchanged. Initialize them once at module load, gated on an env var so local dev and unconfigured bra