@lunora/platform-node is the Node host: the @lunora/platform contracts
(ShardHost, SocketHost, ShardDirectory, ShardKvStore, SchedulerHost)
implemented over better-sqlite3 and an in-process registry, plus .global()
tables over @lunora/sql-store, workflows over @visulima/workflow, and object
storage on the local filesystem.
import { createNodePlatform } from "@lunora/platform-node";
const platform = createNodePlatform({ path: "./shard.sqlite3" });
// …or with the emulated tiers bound. Each is a declaration: omit it and the
// corresponding member is `undefined` rather than an empty host.
const full = createNodePlatform({
globalTablesPath: "./.lunora/global.sqlite3", // → platform.globalTables, its own file
objectStorageDirectory: "./.lunora/bucket", // → platform.objectStorage
onQueueBatch: dispatchQueueBatch, // required alongside `queues`
path: "./shard.sqlite3",
queues: { emails }, // → platform.queues
workflows: { orderPipeline }, // → platform.workflows, runs in the same SQLite file
});Status
Experimental, and not a shipping target. There is no lunora dev --target node; this package ships no dev server. A @lunora/config deploy driver
(node) does exist, but provision is a reporting step, not a writing one: it
tells you, once, which declared features this target cannot serve, and it has
no toolchain to shell out to (no wrangler-equivalent), because there is
nothing remote to deploy to, tail logs from, or store secrets in.
Its API snapshot is gated at the experimental tier
(scripts/api-snapshot.js): a diff here is a public-API change and must be
reviewed as one. This package is Experimental: the snapshot records how its surface
moves, and carries no SemVer promise until the package graduates
(ROADMAP.md's graduation bar).
scripts/check-roadmap-tiers.js fails the install if the roadmap and the
snapshot tier ever disagree.
Read the table below as an honest self-rating, not an invitation to run production traffic on it.
Capability matrix
Reproduced from NODE_CAPABILITIES in @lunora/platform
(packages/platform/src/capabilities/node.ts). This is the same matrix codegen
gates ctx.* surfaces on, not a second copy of it.
pnpm run lint:node-capabilities-docs fails if this table and the source
disagree.
| Feature | Level | Notes |
|---|---|---|
shardedState | emulated | One better-sqlite3 database per shard key, one process — no distributed placement or failover. Shard keys are percent-encoded into basenames with A-Z escaped, so Tenant and tenant stay two databases on a case-insensitive volume (APFS, NTFS) rather than folding into one. There is also no input gate: Cloudflare defers every other dispatch for the span of a mutation, whereas this host can only refuse — SQL issued from another task while a transaction is open throws a retryable SHARD_UNAVAILABLE (503) rather than reading rows that are about to roll back, so a read that merely arrived mid-mutation is retried instead of failing the request |
globalTables | emulated | The @lunora/sql-store core on its own SQLite file via the reference sqliteDialect — full store semantics, but one node with no replication |
websocketHibernation | emulated | Socket registry with attachments/tags persisted to SQLite, and createNodeSocketHost can rehydrate a row into a handle — but restoreSocket is not a SocketHost member and neither createNodePlatform nor createNodeShardRegistry surfaces it, so nothing composed here reassociates a reconnecting client; the conformance host is its only caller. Nothing is ever actually evicted from memory either, so this is durability without hibernation's memory saving and without its rehydration |
workerLoaders | unsupported | No isolate loader: Node has no V8-isolate sandbox for untrusted code, and a node:vm context is not a security boundary |
typedWebSockets | emulated | Rooms and defineWebSocket routes take real network clients: createNodeHttpServer completes the WebSocket handshake through the worker, and the embedder binds the shard with bindShardSockets so inbound frames and closes reach the shard. The socket registry is one process, so a route's broadcast does not fan out to another process, and nothing reassociates a reconnecting client, so a room's membership does not survive a restart |
liveStreams | emulated | Served in this process, by the same ShardDO live handlers Cloudflare runs: connect, subscribe and publish reach the shard through the in-process registry, and createNodeHttpServer streams the SSE body back unbuffered, so a frame reaches the client as it is published. A client that disconnects cancels the body, which drops the subscriber. ctx.live.publish from an HTTP action reaches the subscribers of the shard it names. The embedder composes it: createWorker over createNodeShardNamespace(registry.directory), with one ShardDO kept per shard for the life of the process, since a ShardDO built per request loses its subscribers. A queue consumer's ctx.live comes from the worker's queue export: createWorker's queue(batch, env, ctx) builds the publisher over the same shard forwarding the HTTP action uses, and createNodePlatform's onQueueBatch is the seam that batch is delivered through. A scheduled job's publish takes the same in-process path but is not exercised on this host. Emulated, not native, because the subscriber registry lives in one process: there is no cross-process fan-out, and no keepalive comment frame is sent, so a reverse proxy that idles out a silent stream will close it and the client reconnects |
durableStreams | unsupported | The transcript store is host-neutral (@lunora/shard-engine), but the attach/produce state machine lives in @lunora/do and nothing in this host mounts it. Gate-bearing: codegen refuses an app that declares a durable stream on this target, rather than emitting one that silently behaves as an ephemeral stream |
localSql | native | better-sqlite3 (synchronous, embedded) |
commitOrderedTables | emulated | The sequence orders commits correctly, but the serialization it depends on is Lunora's per-shard write gate rather than a platform property — one process, one better-sqlite3 handle per shard key. Correct here; not something the host guarantees the way a Durable Object does |
deliveryAuthorization | unsupported | Not exercised by this host's conformance suite, and its socket registry does not reassociate a reconnecting client, so the permits a hibernated socket carries have nothing to restore into. Rate it once the suite drives an authorized RPC, a subscription and a fence install |
conditionalWrites | native | SQLite decides it on both paths: shard-local in one synchronous better-sqlite3 run, .global() in one conditional UPDATE on the host's own SQLite file (one node, so nothing to replicate) |
objectColumnPaths | native | json_extract on both paths, over better-sqlite3. It is the same SQLite statement the engine tests run on node:sqlite; it has not been run through better-sqlite3 itself in this host's suite |
queryExplain | native | EXPLAIN QUERY PLAN on better-sqlite3 for both paths. It is the same SQLite statement the engine tests run on node:sqlite; it has not been run through better-sqlite3 itself in this host's suite |
memoryTables | emulated | Same shape as Cloudflare and for a different reason: better-sqlite3 CAN open :memory:, but a shard's memory tables share the one handle its durable tables use, so they are cleared rather than never written. A host process also outlives far more than a Durable Object does, so cold starts — and therefore onShardInit — are much rarer here than in production on Cloudflare; do not use this target to judge how often a memory table is actually empty |
serverReactors | emulated | Same engine-level implementation as Cloudflare; the per-shard serialization it depends on is the host's own write gate rather than a platform guarantee |
alarmRearmBreaker | emulated | Lunora's own counter, not a platform primitive: the poll alarm's re-arms that are due sooner than the 2 s floor are counted in one row of the shard's SQL (ShardHost.sql) over a sliding window, and a re-arm past the budget is refused, leaves one recovery wake a window out, and is logged once per trip. Re-arms at or beyond the floor are checked against that row and never written to it, so a poll at 2 s or slower costs no SQL write. The arm it gates is ShardHost.alarms, so it runs wherever the shard has durable SQL and alarms |
deploymentPause | unsupported | No SchedulerDO on this host, which is where the pause flag lives and what holds scheduled jobs while paused: the admin route answers PAUSE_NOT_CONFIGURED and GET reports supported: false. The router, cron and queue checks are host-neutral runtime code and would apply unchanged given a durable home for the flag |
scheduleRateBreaker | emulated | Lunora's own counter, not a platform primitive: each ctx.scheduler target's schedules are counted per shard in one row of the shard's SQL (ShardHost.sql) over a sliding window, once per invocation, and a schedule past the budget is deferred one window instead of being refused or dropped. The schedules it defers are stored through SchedulerDO, so it runs wherever the shard has durable SQL and a scheduler |
shardAlarms | emulated | setTimeout over a durable row, dispatched to onAlarm and re-armed on construction, so an alarm survives a restart and one whose time elapsed while the process was down fires late rather than never. Delivery is at-least-once as it is on workerd: a handler that throws is re-delivered with exponential backoff (6 attempts, from 100ms) and then abandoned, and an alarm set or deleted inside a transaction is armed only if that transaction commits |
shardPlacement | unsupported | One process — every shard lives where the process does, so a location hint has nowhere to place it |
shardReadReplicas | unsupported | One process and one region: a replica here would be a second copy of a database already on the same disk |
crossShardFanout | emulated | @lunora/runtime's query coordinator over the in-process shard registry; listShardKeys is seeded from the shard files on disk, and answers every shard rather than only those holding the table (a correct superset, at the cost of visiting shards with nothing to say). That registry is the host's own, so the write-time ShardRegistryDO registration a Cloudflare shard does has nothing to report to here and does not run |
queues | emulated | createNodeQueueHost (@lunora/platform-node) — a QueueBindingLike producer per declared queue over a durable _lunora_queue_messages table, and a batched consumer feeding the same dispatchQueueBatch the Cloudflare host uses. delaySeconds (capped at 24h), all four content types, maxBatchSize/maxBatchTimeout assembly, per-message ack/retry with workerd's implicit-ack-on-return and retry-on-throw, retryDelay, maxRetries into a declared deadLetterQueue (or parked in place, never dropped), and a visibility window so a crash mid-handler redelivers. Delivery is driven by poll(); there is no timer, because this host has no dev server to own one. maxConcurrency is ignored: poll() delivers at most one batch per queue and settles it before moving on. Cloudflare's byte ceilings are enforced on send — 128 KiB per message and 256 KiB per sendBatch, measured over the encoded body — because @lunora/queue leaves both to the platform and this host is the only point where those bytes already exist. mode: "pull" queues are written but not consumed — nothing here serves the HTTP pull endpoint. message.run and ctx.run reach a Lunora function through the scheduler dispatch route, which createNodePlatform serves in-process (no HTTP listener, host-backed through the queue onBatch seam, not a provider API): the app worker's queue export takes it as queueFetchImpl (createWorker), set to platform.dispatch, and the route calls the shard through the platform's directory. The route authenticates with LUNORA_SCHEDULER_SECRET (HMAC) or LUNORA_ADMIN_TOKEN, and refuses workflow and pool targets with a 400. Gap: without queueFetchImpl the call goes to LUNORA_ORIGIN_URL, which nothing on this host answers, so the batch retries until maxRetries sends it to the deadLetterQueue or parks it |
workflows | emulated | createNodeWorkflowHost (@lunora/platform-node) binds each workflow on env under its class name — the key ctx.exports carries on Cloudflare — and compiles defineWorkflow handlers onto the @visulima/workflow engine (createRuntime): step/sleep/waitForEvent are durable + replay-safe, status maps to complete/errored/waiting/terminated, create({ id }) is honoured through a durable alias row (so ctx.spawn resolves and a retried create is one run), and runs survive a restart when backed by createNodeWorkflowStore (a SQLite WorkflowStore; the store is required, so no caller silently gets in-process-only state). step.do's per-step retries and rollbacks are emulated by the adapter, not the engine: the attempt loop runs inside the one memoized step, so a crash mid-backoff restarts that step at attempt 1 rather than resuming the countdown, and compensations are plain calls unwound in reverse declaration order, so the adapter ignores rollbackConfig's retries and a crash mid-unwind leaves it half-done (@lunora/workflow itself still reads rollbackConfig.timeout to end a rollback's decline wait). A retries.delay function is awaited in that same loop and its result replaces the backoff, as on Cloudflare. defineWorkflow's limits and defaultRetention are wrangler settings this host never reads: no per-instance step cap is enforced, and a finished run's state stays until it is deleted. delete and deleteBatch (capped at 100 ids) drop a run's stored state behind the same in-process barrier as terminate, but leave no tombstone, so a deleted run's status reads unknown. terminate is a barrier within the process: a terminated run's writes are dropped, so an activation already in flight cannot overwrite the tombstone — it is not a barrier across processes, which would need the lease rather than a set. Gaps: step.do's config.timeout is not emulated — the callback receives no AbortSignal, so a timeout here could only reject while the work it was meant to cancel kept running. @lunora/workflow still ends a ctx.runStep decline wait 2s before the step's timeout (Cloudflare's 10-minute default when unset), so here that wait charges an attempt the host would not have ended, and the next attempt resumes it; no pause/restart; subscribe rejects NOT_IMPLEMENTED, since the engine keeps no per-instance event log to replay; ctx.run has no in-process seam on this host: createNodeWorkflowHost passes no fetchImpl to createWorkflowRunContext, so it still POSTs to LUNORA_ORIGIN_URL, which nothing here answers; ctx.parallel's synchronous join cannot interleave within one trigger activation |
workflowRollback | emulated | createNodeWorkflowHost unwinds each settled step's rollback in reverse declaration order when a later step fails its last attempt. The compensations are plain calls, not durable steps — a crash during the unwind leaves it half-done — and rollbackConfig is ignored |
scheduler | emulated | SQLite job table dispatched to onDispatch and re-armed on construction, with finite retry backoff and a dead-letter queue. This host's schedule() refuses retry.forever as INVALID_INPUT before a job is persisted or armed. ctx.scheduler does not call schedule(): it posts to the SchedulerDO namespace the app's .scheduler() declaration binds, so whether a ctx.scheduler call can retry forever is decided by what backs that binding, not by this host. It is also the only host implementing runtime cron registration (SchedulerHost.cron), which Cloudflare cannot offer — but nothing walks an app's DECLARED crons into that method, which is why cronTriggers is rated separately and unsupported here. This rating covers the imperative surface only: ctx.scheduler.runAfter/runAt do dispatch on this host |
relationGraph | emulated | Identical to Cloudflare: the same engine-level traversal over the same ctx.db reads, served here by better-sqlite3 through this host's per-shard handle. One process and one disk, so a deep expansion is if anything cheaper than on workerd; what it is not is a platform feature |
cronTriggers | unsupported | No runtime walks the generated LUNORA_CRONS map into SchedulerHost.cron, so the conformance suite is that method's only caller and a declared cron does not fire on this host. Gate-bearing: codegen refuses an app that declares one here rather than letting it deploy green and never run. Schedule the work explicitly with ctx.scheduler.runAfter/runAt instead |
authJurisdictionMove | unsupported | Not applicable rather than missing: this host has no jurisdictions. A single process cannot restrict where state lives, so the shard registry offers no jurisdiction() and a worker built for a schema that declares one fails closed at construction. There is never a pinned auth object to copy into, so the admin ops are never wired |
agents | unsupported | Nothing here mounts the generated agent classes: createNodeWorkflowHost compiles defineWorkflow handlers onto the @visulima/workflow engine, and an agent is a generated WorkflowEntrypoint resolved by its class name off ctx.exports or env, and this host binds neither. That missing mount is the whole gap: inference is not, since a model factory or AI SDK model object needs no binding and ai is emulated here through LUNORA_AI_PROXY_URL |
objectStorageBackups | emulated | The commands work unchanged, but the bucket underneath is createNodeR2Bucket — a directory on the same machine the CLI runs on, so a bucket-backed backup here is not the separate failure domain it is on Cloudflare. The scheduled half additionally needs this host's scheduler, which exists but is not a shipping target |
objectStorageCdcArchive | emulated | createNodeR2Bucket implements the startAfter seek the segment index needs, so the read-back behaves as it does on R2. Same caveat as the backups above: the bucket is a directory on the machine running the host, so archiving the changelog here moves it off SQLite but not off the disk that would take the shard with it |
objectStorage | emulated | createNodeR2Bucket (@lunora/platform-node) — an R2BucketLike over the local filesystem (fs/promises, head/list/range). One file per object with the metadata in a trailer, so the single rename that publishes the bytes publishes their checksum and content-type with them, and a get reads body and metadata through one handle rather than reopening the path. put streams into the staged file and .body streams the requested range; .arrayBuffer()/.text() still allocate the range they return. The body is single-use, as R2's is. Keys are percent-escaped per path segment (%, A-Z, :, and a trailing . or space), so A and a stay two objects on a case-insensitive volume exactly as they are on R2, and a lowercase key containing no % or : and no segment ending in . or a space still maps to a byte-identical filename. The limits R2 would apply are applied here rather than left to the deploy to discover: put verifies a declared sha256 against the bytes received and stores nothing on a mismatch, and refuses customMetadata over R2's summed 2048-byte ceiling. Because R2 has no directories, neither does this bucket's behaviour — a deleted key's empty directory is pruned, so a later object may take that prefix, and delete of a key that is only a prefix is the no-op it is on R2 rather than a raw fs error. put honors R2's onlyIf etag preconditions (etagMatches, etagDoesNotMatch, *), checked and published under a per-key lock in this process, and delete takes one key or a batch. No multipart uploads and no presigned URLs, so the binding-backed resumable upload provider (@lunora/storage/upload) finishes only files under 5 MiB here: a larger one needs a multipart upload |
keyValueStore | emulated | better-sqlite3 table behind the ShardKvStore API — not a dedicated KV product |
vectorStore | unsupported | No Vectorize-equivalent binding implemented, so codegen emits neither ctx.vectors nor the backfillVectors override; the admin op answers NOT_IMPLEMENTED, and an index's declared model is accepted but read by nothing |
ai | emulated | No Workers AI-equivalent binding implemented, so @cf/… ids, ctx.ai.run, ctx.ai.websearch and the rejectIfBusy option are unavailable. <provider>/<model> slugs route to the OpenAI-compatible proxy named by the LUNORA_AI_PROXY_URL env var (LiteLLM, OpenRouter, a self-hosted one; bearer token in LUNORA_AI_PROXY_TOKEN) over plain fetch instead of AI Gateway, and a bring-your-own AI SDK model passes straight through. ctx.ai.toMarkdown and @cf/… image ids are unavailable (no binding); ctx.ai.images.generate takes openai/<model> slugs through the proxy, or the provider's own env key without one |
aiSearch | unsupported | No AI Search-equivalent binding implemented, so codegen omits ctx.aiSearch. A REST-backed emulation (account id + API token over fetch) was considered and not built: the REST and binding APIs differ, and nobody on this target has asked for it |
browser | unsupported | No headless-browser binding implemented |
images | unsupported | No Images-equivalent binding implemented |
containers | unsupported | No container orchestration implemented, so there is nothing for ctx.containers.<name>.exec, spawn or terminal to run a command in either |
containerEgressPolicy | unsupported | No container orchestration implemented, so there is no container egress to police |
containerRuntimeScheduling | unsupported | No container orchestration implemented, so there is no image to pick at start and no filesystem to snapshot |
containerSandboxTools | unsupported | No container orchestration implemented, so there is no container filesystem to read, back up or mount a bucket into |
analytics | unsupported | No Analytics Engine-equivalent binding implemented |
analyticsSql | unsupported | No Analytics SQL-equivalent binding implemented, so codegen omits ctx.analyticsSql. Not rated emulated on the strength of createAnalyticsSqlRest: that transport queries Cloudflare's hosted analytics with an API token, so it reads data a Node host never wrote, and an app can import it directly without the ctx surface |
artifacts | unsupported | No Artifacts-equivalent binding implemented: a host would need a Git server with repo-scoped tokens, which no host contract carries |
edgeRequestMetadata | unsupported | Nothing injects per-request platform metadata here — a Node request carries only what the caller wrote. Two telemetry surfaces degrade silently as a result: trustInboundTraceContext: "mtls" can never be satisfied, so it collapses to never-trust and every inbound traceparent is dropped (the runtime warns once when that actually happens, since no codegen gate can see a createWorker option), and the OTLP resource detector finds no placement attributes, so spans ship without them |
hostTraceFusion | unsupported | No host-native trace tree to merge into, and cloudflare:workers is not importable here. Already capability-probed at runtime, so fuseCloudflareTraces is a no-op rather than a throw; onSpan remains the source of truth for the waterfall either way |
logArchive | unsupported | createNodeR2Bucket is a directory on the local filesystem with no Iceberg catalog over it and no SQL engine to query it back, so records could be written but never read. The admin route is still registered here: it answers LOG_ARCHIVE_NOT_CONFIGURED (which the studio renders as a not-configured empty state) only while the logArchive table or the R2 SQL credentials are absent. Configure both and it stops failing closed — it builds an R2 SQL client and queries Cloudflare's API over the network, which is not this host serving the archive |
pipelines | unsupported | No Pipelines-equivalent binding implemented |
pointInTimeRecovery | unsupported | better-sqlite3 keeps no change log to rewind, and createNodeShardState deliberately exposes no bookmark methods rather than a stub that would report a restore that never happened, so getPitrBookmark / pitrRestore answer PITR_UNAVAILABLE. Recover from lunora backup snapshots instead (objectStorageBackups) |
adminTokenRevocation | unsupported | Nothing on this host binds the AdminRevocationDO namespace (createWorker adminRevocations), so no named admin token can be created and any that exist are refused (ADMIN_TOKEN_NOT_CONFIGURED); the root LUNORA_ADMIN_TOKEN is the only admin credential. There is no point-in-time restore here to revive a revoked token either |
mail | unsupported | The queue tier this host lacked when the rating was written now exists (createNodeQueueHost), but nothing here composes a @lunora/mail transport or the queued-send consumer, so a send would be accepted and never delivered |
secrets | unsupported | No Secrets Store-equivalent binding implemented (a real host would likely map this to env vars). Gate-bearing, and it has to be: ctx.secrets is a core built-in spliced into every context, so codegen refuses an app that reads it on this target instead of emitting a surface that throws on first use |
secretValues | unsupported | No store for human-supplied values. Agents are unsupported on this target (see agents), so nothing requests one, and no plaintext node store is built: a value written to local disk would be unencrypted |
services | unsupported | No sibling-Worker host: a Node process runs one app, with nothing a service binding could point at. Gate-bearing, so codegen omits ctx.services instead of emitting bindings that resolve to nothing |
topics | emulated | Each subscription is a createNodeQueueHost queue, so a publish is one durable insert per subscription into _lunora_queue_messages. A subscription handler's message.run goes through the same in-process dispatch route as the queues row, and needs the same wiring |
hyperdrive | unsupported | No connection-pooling binding implemented |
httpCache | unsupported | Nothing sits in front of this host to cache its responses, and Node exposes no Web Cache API global — the runtime's REST edge cache finds no HttpCacheLike here and degrades to emitting Cache-Control alone, which browsers and any CDN in front still honour |
requestOrigin | emulated | The same runtime code reads it off request.url, but nothing here serves HTTP: the embedding server builds that Request, usually from the Host header the caller sent. Pin the host in the proxy in front, or configure a base (publicBaseUrl / STORAGE_PUBLIC_BASE_URL), which always wins over the origin. Because the caller can choose it here, never build links delivered to OTHER people from ctx.origin (password-reset or invite emails, webhooks, notifications): that is host-header poisoning. Use a configured canonical base URL for those; a signed URL returned to the same caller is fine |
identityProxy | unsupported | Nothing sits in front of this host to authenticate callers, so it never populates the execution context's access identity. @lunora/cloudflare-access still works here through its Cf-Access-Jwt-Assertion fallback, which is a plain header check and needs no host support |
workflowSchedules | unsupported | createNodeWorkflowHost only runs instances something creates: nothing reads a workflow's schedules list, so a scheduled workflow would never start. Gate-bearing: codegen refuses an app that declares one here. Start it from a mutation with ctx.workflows.get(name).create() instead, re-armed through ctx.scheduler.runAt |
Almost nothing here is rated native, and that is the matrix's own definition
doing its job rather than a hedge: native means the platform itself provides
the feature, and a bare Node process provides essentially none of them.
localSql is the exception, because SQLite genuinely is the platform primitive
there.
What it is for today
Dev and test. It exists to run the same conformance suite
(@lunora/platform/conformance, @lunora/shard-engine/conformance) against a
second host so portability is a construction check rather than a claim, and it
is a useful in-process double for exercising app code without Cloudflare
credentials. It is not wired into lunora dev, is not a deploy target, and the
capabilities above (one process, no distributed placement or failover, no
Cloudflare product bindings) mean it is not a substitute for the Cloudflare
host in anything that needs them.
On-demand profiling
createNodeProfileHandler({ token }) captures a CPU or heap profile of the
running process through the built-in node:inspector Session, wrapped in
promises, with no native addon and no flag at boot. It serves the result as a
gzip pprof that go tool pprof, Pyroscope and Speedscope read. The app mounts
the handler on a bearer-guarded POST route of its own choosing, and
lunora profile --target node --url <route> calls it. A CPU capture only sees work that runs during the window. A heap capture
reports the allocations still live when it stops. Functions V8 had already
inlined before a CPU capture began can appear under their caller rather than
under their own name.
The profiler runs one capture at a time per process, and the handler refuses an
empty token when it is created. Profiling is not a ctx.* surface or binding,
so it has no entry in PlatformCapabilities.
Known divergences
node-kv-store's serializer is not Cloudflare's, and is not even a stable
wire format on its own. ShardKvStore.put's contract says a value must be
structured-clonable and hosts serialize it durably, without pinning a wire
format. Cloudflare's state.storage uses the platform's own structured-clone
implementation. This host stores values as node:v8's serialize/deserialize
output, the same structured-clone algorithm V8 uses for postMessage and
structuredClone itself, so it round-trips Date, Map, Set, RegExp, and
typed arrays, genuinely closer to Cloudflare's fidelity than JSON.stringify
would be. But node:v8's format is explicitly documented by Node as not a
stable cross-version wire format: a value written under one Node/V8 version is
not guaranteed to deserialize under another. A SQLite file carried across a
Node upgrade can fail to read back values it wrote. See
packages/platform-node/src/node-kv-store.ts and
plans/234-node-host-findings.md.
API
Every public export of src/index.ts, plus the conformance entry point.
createNodePlatform
Type: (options?: NodePlatformOptions<Queues, Workflows>) => NodePlatform<Queues, Workflows>
Composes every contract this package provides over one better-sqlite3 database
file. The queues, workflows, objectStorage and globalTables members are
undefined when the matching option (queues, workflows,
objectStorageDirectory, globalTablesPath) is omitted. Call drain() and then
close() for a graceful shutdown. After close(), scheduler.schedule() and
shard.alarms.set() throw.
NodePlatform
Type: interface
The object createNodePlatform returns. It exposes shard, kv, sockets,
scheduler, directory, dispatch, capabilities, drain, close and
[Symbol.dispose], plus the optional queues, workflows, objectStorage and
globalTables members described above.
NodePlatformOptions
Type: { dispatch?, globalTablesPath?, objectStorageDirectory?, onQueueBatch?, queues?, workflows? } & NodeSchedulerHostOptions & NodeShardHostOptions & NodeShardRegistryOptions
The options for createNodePlatform. The shard host reads path, shardKey and
onAlarm, the scheduler reads onDispatch, and the shard registry reads
directory, onAlarm and onFetch. queues requires onQueueBatch, which the
platform calls for each assembled batch.
NodePlatformDispatchOptions
Type: { adminToken?: string; schedulerSecret?: string }
The secrets the dispatch route checks. adminToken must match the
LUNORA_ADMIN_TOKEN the queue caller sends. schedulerSecret verifies a signed
scheduler body. With neither set, the route refuses every request.
createNodeDispatchRoute
Type: (options: NodeDispatchRouteOptions) => (request: Request) => Promise<Response>
Builds the in-process dispatch route. Mount the returned handler at
NODE_SCHEDULER_DISPATCH_PATH yourself. The route does not register a path.
NODE_SCHEDULER_DISPATCH_PATH
Type: "/_lunora/scheduler/dispatch"
The path @lunora/dispatch and @lunora/scheduler post to.
createNodeGlobalStore
Type: (options?: NodeGlobalStoreOptions) => NodeGlobalStore
Creates the .global() backend on its own SQLite file, using the
@lunora/sql-store core. writer(options) returns the createSqlCtxDb facade
that a shard's d1 thunk expects.
createNodeSqlExec
Type: (database: Database.Database) => SqlCtxExec
Builds the SQL executor over a better-sqlite3 connection. Its transaction
holds BEGIN IMMEDIATE open across the awaits of an async closure.
createNodeHttpServer
Type: (options: NodeHttpServerOptions) => Promise<NodeHttpServer>
Serves an app worker's fetch over node:http and resolves once the server is
listening. fetch is required. host defaults to the loopback interface.
createNodeProfileHandler
Type: ({ token }: NodeProfileHandlerOptions) => NodeProfileHandler
Builds a fetch-style handler that captures a CPU or heap profile of the running
process. It accepts POST requests with Authorization: Bearer <token>. The
token option is required and non-empty, and creating the handler throws when it
is empty.
NodeProfileHandlerOptions
Type: { token: string }
The bearer token the profile handler checks, compared as SHA-256 digests.
createNodeQueueHost
Type: <Queues>(database: Database.Database, options: NodeQueueHostOptions<Queues>) => NodeQueueHost<Queues>
Creates the queue host over the _lunora_queue_messages table, with one producer
binding per declared queue. Delivery runs on poll(), because the host owns no
timer.
createNodeR2Bucket
Type: (options: NodeR2BucketOptions) => R2BucketLike
Creates a bucket over a local directory, with one file per object. Use it with
createStorage({ bucket, bucketName }).
createNodeSchedulerHost
Type: (database: Database.Database, options?: NodeSchedulerHostOptions) => NodeSchedulerHost
Creates a scheduler whose jobs persist in a SQLite table and re-arm on
construction. onDispatch receives due jobs. Its schedule() refuses
retry.forever.
createNodeShardHost
Type: (options?: NodeShardHostOptions) => { database, dispose, drain, host }
Creates the single-writer shard host over a better-sqlite3 database. path is
the database file. dispose() clears the pending alarm timer and closes the
database together.
createNodeShardKvStore
Type: (database: Database.Database) => ShardKvStore
Builds the key-value store over a better-sqlite3 table in the shard's database.
Values use node:v8 serialization, so see Known divergences.
createNodeShardNamespace
Type: (directory: DirectShardDirectory) => ShardNamespaceLike
Presents a shard registry as the namespace a worker is built over
(createWorker({ shardDO })). Both idForName and idFromName return the key
itself.
createNodeShardRegistry
Type: (options?: NodeShardRegistryOptions) => NodeShardRegistry
Builds the in-process shard registry. directory names the folder that holds one
SQLite file per shard. Omit it for in-memory shards, which do not survive a
restart. onAlarm and onFetch are the registry's delivery hooks.
createNodeShardState
Type: (shard: NodeShard) => NodeShardState
Builds the DurableObjectState-shaped object for a shard. It omits the native
point-in-time-recovery methods, so getPitrBookmark and pitrRestore answer
PITR_UNAVAILABLE.
bindShardSockets
Type: (shard: ShardSocketHooks, inbound: Pick<NodeShard["inbound"], "onClose" | "onMessage">) => void
Delivers a shard's inbound socket events. Call it once for each shard instance,
at the point where you build the shard. Cloudflare calls webSocketMessage and
webSocketClose for you, but Node does not.
createNodeSocketHost
Type: (database: Database.Database) => NodeSocketHost
Builds the socket registry. Attachments and tags persist to database. The
returned socket member implements SocketHost.
createNodeWorkflowHost
Type: <Workflows>(options: NodeWorkflowHostOptions<Workflows>) => NodeWorkflowHost<Workflows>
Compiles each declared workflow onto the @visulima/workflow engine. It requires
a store from createNodeWorkflowStore, so runs survive a restart.
createNodeWorkflowStore
Type: (database: Database.Database) => WorkflowStore
Builds the durable workflow store over a better-sqlite3 connection. Pass the
result to createNodeWorkflowHost({ store }).
createNodeConformanceHost
Type: () => ConformanceHost
Imported from @lunora/platform-node/conformance. Builds a fresh host over an
in-memory better-sqlite3 database for one run of the @lunora/platform
conformance suite.
NodeShardRegistryOptions
Type: { directory?: string; onAlarm?: (shard: NodeShard) => Promise<void> | void; onFetch?: (request: Request, shard: NodeShard) => Promise<Response> | Response }
Options for createNodeShardRegistry. Omit directory for in-memory shards.