Node.js Runtime #

View this page as Markdown

On this page

Node.js Runtime is the platform's startup code, called the runtime harness, which the platform loads before your deployed Node.js application's server starts. It checks incoming requests, routes outbound connections through the platform's proxy, records outbound connections, and enforces request deadlines. The platform injects the settings that turn these protections on at every deploy and promote, so the harness behaves the same in every environment your application has. Deploy from your computer describes each step of a deploy.

Use it when #

Every application deployed through the platform's image build uses Node.js Runtime automatically. There is no handler function to export: supply an ordinary Node.js HTTP server that listens on PORT.

The platform starts it with npm start, using scripts.start in the root package.json or npm's default, a root server.js. The hello-world template shows a complete server.

In a deployed copy, the platform sets PORT to 8080. The manifest cannot change it. Your application runs on Node.js 24, whatever the engines field in its package.json says (What the application runs under). You install nothing for the runtime harness, and a tzTeam project writes no instance file for it. Read this page when you choose an HTTP client, handle request cancellation, or diagnose refused and interrupted requests.

The manifest's egress list defines the outbound destinations, and the platform's proxy applies its own checks on authentication, destination, and port. Egress firewall and request limits describes both. Node.js Runtime points supported clients at that proxy. It does not replace the proxy's checks or the hosting network's rules.

What it provides #

  • Incoming-request checks on the Node.js HTTP server. A request from another machine without the router mark, a secret header the serving router adds, receives 403 router_mark_required before your application's listener runs. A loopback request is accepted without a mark. The checks also cover HTTP upgrade and CONNECT requests. A separate HTTPS or HTTP/2 server is not covered. The harness removes the mark header from every request it accepts, so your application's request listener never sees it. It also removes the mark setting from your application's environment and keeps the marks in a file only the container's own user can read.
  • Idle HTTP connections. On a deployed copy, the harness sets an HTTP server's idle keep-alive to 290 seconds and its headers timeout to 295 seconds, if its keep-alive is still Node.js's five-second default. This prevents the service forwarding requests to your server from reusing a connection your server has closed. An application-set keep-alive and the request timeout are left unchanged. Separate HTTPS and HTTP/2 servers, and local runs, are not covered.
  • A check on scheduled-handler paths. A request to a schedule's path without the router's schedule-invocation header receives 404 scheduled_handler_only. The mark check runs first. The checks use the schedule paths declared at the container's last deploy or promote. A declaration added later reaches the container at the environment's next deploy or promote, and the platform fires a declaration only against a container applied at or after it.
  • Proxy settings: the environment variables HTTPS_PROXY, HTTP_PROXY, and NO_PROXY, and an undici global dispatcher. Global fetch, undici-based clients, and clients that read those variables use the proxy. Platform endpoints and loopback names bypass it.
  • Records of outbound connections under the log source harness: one egress_establishments record per host, port, and outcome per minute, with the count and the first and last instants. Each connection whose outcome is not connected also gets its own egress_establishment record. The harness sends the records through the logging client under your application's own credential, so they outlive the process.
  • An abort signal at request.signal. Requests and scheduled runs can have different deadlines. If the response has not ended within the grace interval after the signal, the harness ends the process. A watchdog also ends a process whose event loop is blocked.
  • A pod's last console lines. Where your application runs as a pod, the harness keeps the first 50 and the last 250 console lines of each process your start script runs. Each is cut at 2,048 bytes. When SIGTERM reaches the process, the harness ships them to your application's log stream before your own SIGTERM handlers run. Sending these lines takes about 50 ms and never more than three seconds. How long console lines last says how long they are kept.
  • The stop signal with the harness. The harness keeps its SIGTERM listener while sending those console lines, so a second signal does not end the process part-way. It then removes its listener. Where you registered no SIGTERM handler, the harness raises SIGTERM again, so the process ends as it would without the harness. If sending the lines fails or takes too long, the harness writes one pod_console_keep_failed line to the console.
  • harness_refusal, window_ended, and process_ended log records, written to the process's standard output and read with the container source. When a process ends, the serving router responds to each other request in flight with 502 upstream_ended if no response header had gone out.

Monitoring or tracing code that loads before the harness can read the mark. That is code loaded with --require, or with an --import your start command puts ahead of the harness's in NODE_OPTIONS, and code that wraps the server to watch upgrade requests. Set such code to capture no x-turnzero-cloud- header. A server in a worker thread is not covered when the thread runs code passed as a string, or when its environment lacks NODE_OPTIONS.

Two records under the container source report problems storing or reading the router marks. router_mark_setting_kept means the harness could not write the marks' file, so the mark setting stayed in the environment. router_mark_file_unread means a process could not read the marks' file, so that process runs with no router-mark check; report the record with its file and code, as Feedback describes. Your application's code never reads the marks' file or the mark setting.

The connection records leave out connections opened by native add-ons and child processes, and connections to platform endpoints and the logging service's own origin. The records of the minute still open when the process ends go to the process's console, not the log stream.

A stack trace from your handler carries frames in file:///harness/harness.mjs after your own, because the harness hands each request to your listener. read_logs leaves those frames out, so a trace it answers shows your own frames and Node's.

Availability #

Version 0.12.0 is the package's current version, and this page describes it. Until the library's next publish, read_library can return an earlier version of its documents. The library publishes only the package's documents. The platform loads the harness ahead of your code, so no application copies or installs it.

A local run loads no harness, so these protections exist only in a deployed copy. A local run's keyed external calls go through the public gateway at TURNZERO_CLOUD_GATEWAY_URL, so the machine stores no provider key. Run your app on your computer states what else a local run uses.

The platform injects every setting the harness reads, so your application sets none of them. If a setting is missing or invalid, the protection it controls is off: no router-mark check, no deadline, or no proxy routing.

Database and Storage use platform endpoints outside the proxy. Secrets provides named credentials for your application's calls. Egress calls external APIs on a stored key through the gateway.

What an application must do #

Declare the outbound HTTPS destinations your application calls in the manifest's egress list. Egress firewall and request limits states the hostname rules and the port. Platform endpoints need no entry.

Read your application's mode as egress_mode in the read_status response. In observe mode, where a new application starts, the proxy records undeclared destinations and permits them. In enforce mode it refuses them with 403 egress_undeclared (Observe before enforce).

Recognize a proxy refusal in your code. Through the harness's dispatcher, global fetch rejects with TypeError: fetch failed, and its cause is an EgressRefusedError. An undici client called on the dispatcher directly receives the EgressRefusedError itself. Every proxy refusal takes this form, among them a wrong credential (407 proxy_authentication_required), a refused port, and a refused address class. Read the error's members:

Member What it contains
error.cause.code === 'EGRESS_REFUSED' True for a proxy refusal.
cause.refusal The refusal's name.
cause.status The proxy's status.
cause.host, cause.port The target.
cause.remedy For egress_undeclared, the manifest edit for a hostname or a fixed sentence for an address literal. Null for every other refusal.

Use a covered HTTP client. Global fetch, undici, and SDKs built on them use the harness's dispatcher, and axios uses the proxy variables. Clients such as node:https, node-fetch, got, and ws need an explicit proxy agent from https-proxy-agent, passed as the client's agent option, or under agent.https for got. Without an agent, a call may fail with a connection error or reach the destination directly, depending on the network rules, rather than meet a named proxy refusal.

Build the agent only where HTTPS_PROXY is set, as in const agent = process.env.HTTPS_PROXY ? new HttpsProxyAgent(process.env.HTTPS_PROXY) : undefined: the harness sets none in a local run, and the constructor throws without it. The variable's URL contains your application's platform credential, so never log or print it. The agent ignores NO_PROXY, so give it only to calls to external hosts: a platform endpoint called through it is refused.

Build every absolute address you hand out, such as a link, a redirect, or a file's URL, from APP_PUBLIC_HOST, the public hostname the platform injects, or from the router's x-forwarded-proto and x-forwarded-host headers. A relative redirect, such as /guestbook, needs neither (Serve a web client, step 7). The Host header names the platform's internal address for the environment, so an address built from it does not resolve outside the platform. Put https:// before the value of APP_PUBLIC_HOST, which has no scheme. What the router sets on each request lists the headers the router sets.

Handle request cancellation #

Handle request.signal, and end the response when it fires. Do no application work outside a handler: the harness does not detect a detached promise, timer, or child process that runs on after the response. A handler that does not end after cancellation can make the harness end the process, which interrupts other requests. Upgraded WebSocket connections are outside the request deadline, although the upgrade request passes through the incoming checks. Use WebSockets covers the declaration and the limits.

A plain node:http server needs no framework for this. On the platform, the harness puts the signal at request.signal on every request the server receives. It fires when the request's execution window ends, not when the client leaves.

In your local run, use a signal that fires when the response closes unfinished, rather than Node's request.signal, which some Node 24 releases abort at a normal request end. The database-service example shows abortSignalOf for this.

Stop cleanly #

Handle SIGTERM to stop cleanly. When the platform stops a running copy, SIGTERM reaches your server's process, so a handler there can close the listener, finish the requests in flight, and exit. Without a handler, Node.js ends the process at once. The platform waits 60 seconds on the pod grain and 30 seconds on the container grain, then kills what still runs.

On the pod grain, the platform's startup code (the runtime harness) sends the process's last console lines first, usually in about 50 ms. A process with no SIGTERM handler ends after those lines are sent. The harness handles the signal through Node.js's event loop, so a process with a busy main thread ends only when its event loop runs again.

The image starts tini -g, which passes SIGTERM to the process group running npm start, including Node.js processes in a pipe such as node server.mjs | tee app.log. The start shell waits for the script's commands rather than ending at the signal. A pipe's reader, such as tee, ends when its input ends. The platform collects standard output under the container source; Read logs and counters says how to read it.

On each version row from list_versions, harness_current compares only the runtime harness bundle, not the image's startup command. An older image that starts npm directly instead of tini can still report true. Deploy a new version to update that startup command. Restarting or promoting the older version keeps its original image.

Keep the server as your start script's last command, alone or after &&, such as node server.mjs or node migrate.mjs && node server.mjs. A command after ;, or after && when the preceding command exits 0, starts even after the stop signal. The signal does not reach a process started after it; that process may run until the grace period ends.

Commands in your start script run under /bin/sh (dash), with SIGTERM ignored by the shell. A long-running non-Node command that inherits this ignored signal runs until the grace period ends. Use plain sh syntax, or move bash-only syntax such as [[ ]], source, or arrays into a script file whose first line is #!/bin/bash.

Deploy the application again to use this process and shell setup. Restarting an older image keeps its existing setup.

Keep data and read records #

Keep no file the application needs again on the running copy's own disk: put files in Storage and records in Database (The local file system does not persist across restarts or redeploys).

Keep the platform credential secret. The platform injects it as TURNZERO_CLOUD_APP_TOKEN, one credential per environment, bound to the environment it was minted for. The proxy's authentication and the harness's own log writes use it. Do not put it in source code or print it in logs.

Read the harness's records with read_logs and the harness, egress, router, and container sources. Read logs and counters states what each source contains, which environment read_logs reads, and how to filter the records by declared and undeclared destinations.

A request past the router's deadline receives 504 window_ended, or its streaming response is cut. Where the process then ends, an intermediary can retry an idempotent request on the restarted process, and that caller then receives the new response. A client address past the router's per-address limit receives 429 rate_capped, and its request never reaches the process. Egress firewall and request limits states the deadline and the bound.

The local file system does not persist across restarts or redeploys #

What a deployed application needs gives the fuller account of where data lasts. A deployed application runs in a container or a pod, and what its code writes to the local disk does not persist. Keep no file the application needs again on the running copy's own disk. A deploy, a promote, a rollback, restart_application, and the platform's own replacement each start a new copy with only what its deploy built, and so does the start after an idle stop. Whatever the code wrote to the disk, /tmp included, is then lost. Put files in Storage and records in Database.

What the router sets on each request #

The serving router sets four headers on every request it forwards to your application:

Header What it contains
x-forwarded-host The hostname the request arrived on.
x-forwarded-proto Always https, because the encrypted connection ends before the router.
x-forwarded-for The client's address as the router knows it. Read the first entry, since a hop after the router may append its own.
x-request-id The router creates one sixteen-character hexadecimal identifier for each request and includes it on every response to that request. A refusal made before the router accepts the request, because of its body or HTTP message format, is the exception.

The router sets the four after the client's headers, so a client's copy never arrives. The Host header names the platform's internal address for the environment, never the public hostname. Build an absolute address from x-forwarded-proto and x-forwarded-host, or from APP_PUBLIC_HOST. The router sets no other forwarding header, such as Forwarded or x-forwarded-port, so trust none. The router also sets the headers of a scheduled run and of a signed-in end user, which those pages describe.

The router passes an application's redirect status and Location header to the caller without following the redirect.

A local run has no router and no APP_PUBLIC_HOST. Fall back to the request's Host header and http. A test that requests a local server expects http addresses, or sends x-forwarded-proto itself.