bare-stow 0.1.6 → 0.1.8

package/README.md

@@ -66,8 +66,12 @@ ipc.on('exit', (code) => {
 ipc.destroy()
 ```
 
+The harness imports its runtime by name, `bare-stow/host` along with `bare-sidecar` or `bare-worker` depending on the target, so the package that the harness is written into must depend on both. Relying on another package to bring them in only works while a package manager happens to hoist them, and not at all under an isolated layout such as that of pnpm. `stow()` resolves every import of the harness from `out` before writing anything and throws if one of them can't be found.
+
 For the `bare-sidecar` target, `start()` accepts the options of `bare-sidecar`. The sidecar inherits the standard streams of the host unless `stdio` says otherwise.
 
+`start()` also accepts `timeout`, the number of milliseconds to wait for the worker to signal ready before rejecting and terminating it, and `grace`, the number of milliseconds a terminating worker gets to run `stop()` and exit before it is killed. `timeout` defaults to waiting indefinitely and `grace` to 5 seconds. The worker holds itself to the same `grace` whenever it shuts down, including when it receives `SIGTERM` or the host goes away without terminating it. On Windows, a sidecar is killed along with its host instead, so `stop()` only runs when the host terminates it.
+
 ## Protocol
 
 The harness multiplexes a control channel and a user data channel over the underlying binary duplex stream. The `ipc` returned from `start()` is itself a duplex stream carrying the user data; control frames ride alongside it on the same handle. RPC libraries (such as `bare-rpc`) bind to `ipc` just like a raw stream.
@@ -114,43 +118,7 @@ const ipc = wrap(stream) // Any duplex byte stream
 await ipc.ready
 ```
 
-## API
-
-#### `const artifacts = stow(entry, target, out[, opts])`
-
-Bundle the module graph rooted at `entry` for a `target` runtime and write the resulting artifacts to disk at and alongside `out`. Returns an async generator that yields `{ url }` objects as each artifact is written, allowing callers to observe progress.
-
-`entry` is a `URL` (or `URL`-coercible string) pointing at the entry module. `target` selects the target runtime, given either as a built-in name (`'bare-sidecar'` or `'bare-worker'`) or as a [target provider](#targets-and-rpc-providers) object. Other targets ship as their own packages; require one and pass it as the provider. The target determines the harness format, bundle extension, host triples, and whether assets and addons are linked into the bundle or offloaded as sibling files. `out` is the output `URL` of the harness; the bundle is written next to it with the target's extension.
-
-The harness artifacts are yielded first: The harness itself at `out`, followed by a TypeScript declaration (`.d.ts`) alongside it so hosts importing the harness are typed. The bundle is yielded next, then any offloaded assets and native addons when the target supports offloading.
-
-Options include:
-
-```js
-opts = {
-  client,
-  server,
-  base,
-  hosts,
-  resolveTarget,
-  resolveRPC
-}
-```
-
-- `client`: The RPC library to wire into the harness as a client, given either as a built-in name (`'bare-rpc'`) or as an [RPC provider](#targets-and-rpc-providers) object.
-- `server`: The RPC library to wire into the bundle entry shim as a server, given either as a built-in name (`'bare-rpc'`) or as an [RPC provider](#targets-and-rpc-providers) object.
-- `base`: The base `URL` of the module graph, which must contain every module in the bundle. Defaults to the closest directory that does.
-- `hosts`: An array of host triples to build for. Must be a subset of the host triples supported by the target; passing a host the target does not support throws. Defaults to all host triples supported by the target.
-- `resolveTarget`: A function mapping a target name to a [target provider](#targets-and-rpc-providers) object, called when `target` is a name not in the built-in registry (which knows `'bare-sidecar'` and `'bare-worker'`).
-- `resolveRPC`: A function mapping an RPC library name to an [RPC provider](#targets-and-rpc-providers) object, called when `client` or `server` is a name not in the built-in registry (which only knows `'bare-rpc'`).
-
-Any additional options are forwarded to `bare-pack`. See <https://github.com/holepunchto/bare-pack> for the full set, including `builtins`, `imports`, `defer`, and `resolve`.
-
-#### TypeScript
-
-TypeScript modules are supported out of the box: `.ts`, `.mts`, and `.cts` sources are stripped of their type syntax with [`bare-type-stripper`](https://github.com/holepunchto/bare-type-stripper) as they are read, and their extensions are aliased to `.js`, `.mjs`, and `.cjs` respectively for module-type detection. The stripper only erases types, so the module system follows the aliased JavaScript extension. Because stripping is purely lexical, non-erasable constructs (`enum`, `namespace` with a body, parameter properties) throw, and JSX (`.tsx`) is not supported.
-
-### Targets and RPC providers
+## Targets and RPC providers
 
 The harness and RPC code generators are decoupled from the bundler: `target`, `client`, and `server` each accept a provider object directly, so generators can live outside `bare-stow`. Passing a name instead resolves it through `resolveTarget` / `resolveRPC`, which default to the built-in registries.
 
@@ -169,7 +137,7 @@ A target provider describes the runtime profile it owns and generates the harnes
 target = {
   name, // The target's name, used in diagnostics.
   linked, // Whether assets and addons are linked into the bundle.
-  offload, // Whether (and which) assets and addons are offloaded as sibling files.
+  offload, // Whether (and which) assets and addons are offloaded to a `<bundle>.d` directory next to the bundle.
   format, // The bundle encoding: 'bundle', 'bundle.cjs', 'bundle.mjs', or 'bundle.json'.
   encoding, // The string encoding for encoded formats, or null for raw bytes.
   extension, // The bundle file extension, e.g. '.bundle'.

package/index.d.ts

@@ -1,63 +1,158 @@
 import URL from 'bare-url'
 import { PackOptions } from 'bare-pack'
 
+/** A single generated source artifact, such as a harness or a type declaration. */
 interface Artifact {
+  /**
+   * The file extension the artifact should be written with alongside the primary output, or unset
+   * to write it to the primary output path itself.
+   */
   extension?: string
+  /** The artifact's source text. */
   source: string
 }
 
 type TargetName = 'bare-sidecar' | 'bare-worker'
 
+/**
+ * The context passed to a target's `generate()`, describing the bundle to embed and the RPC wiring
+ * to splice in.
+ */
 interface TargetContext {
+  /** The module specifier the harness uses to load the bundle, relative to the harness itself. */
   bundleSpecifier: string
+  /** The identifier bound to the IPC stream in generated harness code. */
   ipc: string
+  /** The identifier bound to the RPC client/server in generated harness code. */
   rpc: string
+  /** The module system the harness is generated in, `'esm'` or `'cjs'`. */
   module: 'esm' | 'cjs'
+  /**
+   * The resolved client RPC wiring to splice into the harness, or `null` when no client RPC was
+   * requested.
+   */
   client: RPCClient | null
 }
 
+/**
+ * A bundling target, such as `bare-sidecar` or `bare-worker`, describing how to package and boot a
+ * bundle on a given host runtime.
+ */
 interface Target {
+  /** The target's name. */
   name: string
+  /** Whether the bundle links against its dependencies rather than inlining them. */
   linked: boolean
+  /**
+   * Whether native addons and/or assets are written out as sibling files instead of being inlined
+   * into the bundle.
+   */
   offload: boolean | { addons?: boolean; assets?: boolean }
+  /** The encoding format of the written bundle artifact. */
   format: 'bundle' | 'bundle.cjs' | 'bundle.mjs' | 'bundle.json'
+  /**
+   * The text encoding used when the bundle format wraps the bundle as a string, or `null` when the
+   * bundle is written as raw bytes.
+   */
   encoding: string | null
+  /** The file extension used for the target's harness artifact. */
   extension: string
+  /**
+   * The module system the harness is generated in, `'esm'` or `'cjs'`. When unset, it follows the
+   * output path's extension or nearest `package.json` `type`.
+   */
   module?: 'esm' | 'cjs'
+  /** The host triples the target supports. */
   hosts: string[]
+  /**
+   * Generate the harness artifacts for `context`.
+   * @param context - The target context describing the bundle to embed and the RPC wiring to splice
+   * in.
+   */
   generate(context: TargetContext): Artifact[]
 }
 
 type RPCName = 'bare-rpc'
 
+/** The context passed to an RPC adapter's `generate()`. */
 interface RPCContext {
+  /** The identifier bound to the IPC stream in generated code. */
   ipc: string
+  /** The identifier bound to the RPC client/server in generated code. */
   rpc: string
+  /** The module system the generated code targets, `'esm'` or `'cjs'`. */
   module: 'esm' | 'cjs'
+  /**
+   * Whether the generated wiring is for the `'client'` (harness side) or `'server'` (bundle entry
+   * shim side).
+   */
   role: 'client' | 'server'
 }
 
+/**
+ * An RPC library adapter that generates the wiring code spliced into a stowed bundle's harness or
+ * entry shim.
+ */
 interface RPC {
+  /** The RPC adapter's name. */
   name: string
+  /**
+   * Generate the RPC wiring artifacts for `context`.
+   * @param context - The RPC context describing the identifiers, module system, and role to
+   * generate wiring for.
+   */
   generate(context: RPCContext): Artifact[]
 }
 
+/**
+ * The resolved client RPC wiring, carrying both the runtime source to splice into the harness and
+ * the type declaration to splice into the harness's `.d.ts`.
+ */
 interface RPCClient {
+  /** The generated runtime source for the client RPC wiring. */
   source: string
+  /** The generated type declaration for the client RPC wiring. */
   type: string
 }
 
+/** Options for `stow()`. */
 interface StowOptions extends Omit<PackOptions, 'offload' | 'linked' | 'resolve' | 'aliases'> {
+  /** The RPC library (or its name) to wire into the harness. */
   client?: RPC | RPCName
+  /** The RPC library (or its name) to wire into the bundle's entry shim. */
   server?: RPC | RPCName
+  /**
+   * Resolve a target name to a `Target`, overriding the default target resolution.
+   * @param name - The target name to resolve to a `Target`.
+   */
   resolveTarget?(name: string): Target
+  /**
+   * Resolve an RPC name to an `RPC`, overriding the default RPC resolution.
+   * @param name - The RPC name to resolve to an `RPC`.
+   */
   resolveRPC?(name: string): RPC
 }
 
+/** An artifact written by `stow()`, yielded once its file has been written. */
 interface StowArtifact {
+  /** The file URL the artifact was written to. */
   url: URL
 }
 
+/**
+ * Bundle the module graph rooted at `entry` for `target`, writing a harness plus bundle to `out`.
+ * @param entry - The entry module to bundle, as a `file:` URL or path string.
+ * @param target - The bundling target: a `Target` object, or a target name resolved to one (the
+ * built-in `bare-sidecar` and `bare-worker`, or a `bare-stow-target-<name>` package).
+ * @param out - The path to write the harness to, as a `file:` URL or path string; the bundle is
+ * written alongside it.
+ * @param opts - Options; see [`StowOptions`](#stowoptions).
+ * @returns An async generator that yields each written artifact's `url` as it is produced, starting
+ * with the harness, then the bundle, then any offloaded addon or asset files.
+ * @throws The `target` argument is missing.
+ * @throws The `out` argument is missing.
+ * @throws A host in `opts.hosts` is not supported by the resolved target.
+ */
 declare function stow(
   entry: URL | string,
   target: Target | TargetName,

package/index.js

@@ -4,6 +4,7 @@ const pack = require('bare-pack')
 const id = require('bare-bundle-id')
 const strip = require('bare-type-stripper')
 const { resolve } = require('bare-module-traverse')
+const lex = require('bare-module-lexer')
 const fs = require('./lib/fs')
 const shim = require('./lib/shim')
 const harness = require('./lib/target')
@@ -19,7 +20,7 @@ module.exports = async function* stow(entry, target, out, opts = {}) {
 
   const targetName = typeof target === 'string' ? target : t.name
 
-  entry = new URL(entry)
+  entry = await fs.resolveModule(new URL(entry))
   out = new URL(out)
 
   // The target may pin a module system; otherwise it follows the output path.
@@ -82,12 +83,13 @@ module.exports = async function* stow(entry, target, out, opts = {}) {
     },
     readModule,
     fs.listPrefix,
+    fs.resolveModule,
     writeFile
   )
 
   base = resolveBase(base, bundle)
 
-  bundle = rerootOffloaded(bundle.unmount(base), base, out, offloaded)
+  bundle = rerootOffloaded(bundle.unmount(base), base, bundleURL, offloaded)
 
   bundle.id = id(bundle).toString('hex')
 
@@ -118,6 +120,10 @@ module.exports = async function* stow(entry, target, out, opts = {}) {
     client: clientSetup
   })
 
+  for (const artifact of artifacts) {
+    if (!artifact.extension) await assertImportsResolve(artifact.source, out)
+  }
+
   // The first artifact is the harness written to `out`; any further artifacts
   // are siblings named after `out` with the artifact's own extension.
   for (const artifact of artifacts) {
@@ -130,6 +136,10 @@ module.exports = async function* stow(entry, target, out, opts = {}) {
   await fs.writeFile(bundleURL, encodeBundle(bundle, t.format, t.encoding ?? 'utf8'))
   yield { url: bundleURL }
 
+  // Offloaded files are collected in the order their reads complete, so they
+  // are sorted to keep the output stable.
+  offloaded.sort((a, b) => (a.url.href < b.url.href ? -1 : a.url.href > b.url.href ? 1 : 0))
+
   for (const artifact of offloaded) {
     await fs.writeFile(artifact.url, artifact.source)
     yield { url: artifact.url }
@@ -203,20 +213,22 @@ function collectOffloaded(sink) {
   }
 }
 
-// Offloaded files are written next to the harness, so their resolutions are
-// rewritten to point beside the bundle, along with the directories that hold
-// them, as `bare-pack` does for a bundle packed with a base.
-function rerootOffloaded(bundle, base, out, offloaded) {
+// Offloaded files are written to a directory named after the bundle rather than
+// next to the harness, as a mirrored `node_modules` beside the harness would
+// shadow the packages it imports. Their resolutions are rewritten to point into
+// that directory, along with the directories that hold them.
+function rerootOffloaded(bundle, base, bundleURL, offloaded) {
   if (offloaded.length === 0) return bundle
 
-  const dir = new URL('./', out)
+  const name = path.basename(bundleURL.pathname) + '.d'
+  const dir = new URL(name + '/', bundleURL)
   const rewrites = new Map()
 
   for (const file of offloaded) {
     const relative = offloadedPath(file.url, base)
 
     let key = '/' + path.posix.relative(base.pathname, file.url.pathname)
-    let value = '/../' + relative
+    let value = '/../' + name + '/' + relative
 
     rewrites.set(key, value)
 
@@ -242,6 +254,8 @@ function rerootOffloaded(bundle, base, out, offloaded) {
   }
 
   bundle.resolutions = resolutions
+  bundle.addons = bundle.addons.map((href) => rewrites.get(href) || href)
+  bundle.assets = bundle.assets.map((href) => rewrites.get(href) || href)
 
   return bundle
 }
@@ -274,6 +288,44 @@ function isTerminator(input) {
   return input === '' || input.endsWith('/') || input.endsWith(':')
 }
 
+async function assertImportsResolve(source, out) {
+  for (const entry of lex(source).imports) {
+    const { specifier } = entry
+
+    if (specifier.startsWith('.') || specifier.startsWith('/')) continue
+
+    if (await resolves(entry, out)) continue
+
+    throw new Error(
+      `Harness '${fileURLToPath(out)}' imports '${specifier}', which the package containing it does not depend on`
+    )
+  }
+}
+
+async function resolves(entry, parentURL) {
+  const resolver = resolve.bare(entry, parentURL)
+
+  let next = resolver.next()
+
+  while (next.done !== true) {
+    const value = next.value
+
+    if (value.package) {
+      const source = await fs.readModule(value.package)
+
+      next = resolver.next(source === null ? null : JSON.parse(source))
+    } else {
+      const exists = await fs.isFile(value.resolution)
+
+      if (exists) return true
+
+      next = resolver.next(false)
+    }
+  }
+
+  return false
+}
+
 async function resolveModule(out) {
   switch (path.extname(out.pathname)) {
     case '.mjs':

package/lib/fs.js

@@ -76,3 +76,7 @@ exports.listPrefix = async function* listPrefix(url) {
     }
   }
 }
+
+exports.isFile = isFile
+
+exports.resolveModule = require('bare-pack/fs').resolveModule

package/lib/host.d.ts

@@ -1,19 +1,56 @@
 import { Duplex } from 'bare-stream'
 import { Protocol } from './protocol'
 
+/** Options for `wrap()`. */
+interface IPCOptions {
+  /**
+   * Stop the worker once it has ignored a `terminate` control frame for `grace` milliseconds.
+   * Defaults to destroying `stream`.
+   */
+  kill?: () => unknown
+  /**
+   * The number of milliseconds to wait for the worker to signal ready before rejecting `ready` and
+   * terminating the worker, or `null` to wait indefinitely. Defaults to `null`.
+   */
+  timeout?: number | null
+  /**
+   * The number of milliseconds to wait for the worker to exit after a `terminate` control frame
+   * before calling `kill`. Defaults to `5000`.
+   */
+  grace?: number
+}
+
 interface IPC extends Protocol {
+  /**
+   * A promise that resolves once the worker has signaled ready, and rejects if the worker errors,
+   * exits, or times out before then. The worker is terminated when it rejects.
+   */
   readonly ready: Promise<void>
+  /**
+   * Send a `terminate` control frame to the worker and resolve once it exits, killing it if it has
+   * not exited within the grace period.
+   * @returns The worker's exit `code`, or `undefined` if it closed without signaling one.
+   */
   terminate(): Promise<number | undefined>
 }
 
 declare class IPC {
-  constructor(stream: Duplex)
+  /**
+   * Wrap the host side of a stowed bundle's transport `stream`.
+   * @param stream - The host side of a stowed bundle's transport (any duplex byte stream).
+   * @param opts - Options; see [`IPCOptions`](#ipcoptions).
+   */
+  constructor(stream: Duplex, opts?: IPCOptions)
 }
 
-declare function wrap(stream: Duplex): IPC
-
-declare namespace wrap {
-  export { IPC }
-}
+/**
+ * Wrap the host side of a stowed bundle's transport `stream`, returning an `IPC` handle with
+ * lifecycle helpers layered on top of the `Protocol`.
+ * @param stream - The host side of a stowed bundle's transport (any duplex byte stream).
+ * @param opts - Options; see [`IPCOptions`](#ipcoptions).
+ * @returns An `IPC` handle wrapping `stream`, with the `ready` promise and `terminate()` layered on
+ * top of `Protocol`.
+ */
+declare function wrap(stream: Duplex, opts?: IPCOptions): IPC
 
-export = wrap
+export { IPC, type IPCOptions, wrap }

package/lib/host.js

@@ -1,24 +1,50 @@
-const { Protocol } = require('./protocol')
+const { Protocol, DEFAULT_GRACE } = require('./protocol')
 
 class IPC extends Protocol {
-  constructor(stream) {
+  constructor(stream, opts = {}) {
     super(stream)
 
+    const { kill = () => stream.destroy(), timeout = null, grace = DEFAULT_GRACE } = opts
+
+    this._kill = kill
+    this._grace = grace
+    this._terminating = null
+
+    this.send('configure', { grace })
+
     this._ready = new Promise((resolve, reject) => {
+      const timer =
+        timeout === null
+          ? null
+          : setTimeout(() => onerror(new Error('Worker timed out before ready')), timeout)
+
+      const cleanup = () => {
+        clearTimeout(timer)
+        this.off('ready', onready).off('error', onerror).off('exit', onexit).off('close', onclose)
+      }
+
       const onready = () => {
-        this.off('ready', onready).off('error', onerror)
+        cleanup()
         resolve()
       }
 
       const onerror = (err) => {
-        this.off('ready', onready).off('error', onerror)
+        cleanup()
         reject(err)
       }
 
-      this.on('ready', onready).on('error', onerror)
+      const onexit = (code) => {
+        // An error frame precedes the exit frame and is emitted on destroy
+        if (this.destroying) return
+        onerror(new Error(`Worker exited with code ${code} before ready`))
+      }
+
+      const onclose = () => onerror(new Error('Worker closed before ready'))
+
+      this.on('ready', onready).on('error', onerror).on('exit', onexit).on('close', onclose)
     })
 
-    this._ready.catch(() => {})
+    this._ready.catch(() => this.destroy())
   }
 
   get ready() {
@@ -26,37 +52,44 @@ class IPC extends Protocol {
   }
 
   terminate() {
-    return new Promise((resolve) => {
-      const cleanup = () => {
-        this.off('exit', onexit)
-        this._stream.off('close', onclose)
-      }
+    if (this._stream.destroyed) return Promise.resolve(undefined)
 
-      const onexit = (code) => {
-        cleanup()
-        resolve(code)
-      }
+    return new Promise((resolve) => {
+      this.once('exit', resolve)
 
-      const onclose = () => {
-        cleanup()
+      this._terminate().then(() => {
+        this.off('exit', resolve)
         resolve(undefined)
-      }
-
-      this.once('exit', onexit).send('terminate')
-      this._stream.once('close', onclose)
+      })
     })
   }
 
   _destroy(err, cb) {
     if (this._stream.destroyed) return cb(null)
 
+    this._terminate().then(() => cb(null))
+  }
+
+  _terminate() {
+    if (this._terminating !== null) return this._terminating
+
+    const timer = setTimeout(() => this._kill(), this._grace)
+
     this.send('terminate')
-    this._stream.once('close', () => cb(null))
+
+    this._terminating = new Promise((resolve) => {
+      this._stream.once('close', () => {
+        clearTimeout(timer)
+        resolve()
+      })
+    })
+
+    return this._terminating
   }
 }
 
 exports.IPC = IPC
 
-exports.wrap = function wrap(stream) {
-  return new IPC(stream)
+exports.wrap = function wrap(stream, opts) {
+  return new IPC(stream, opts)
 }

package/lib/protocol.d.ts

@@ -1,22 +1,46 @@
 import { Duplex, DuplexEvents } from 'bare-stream'
 
+/** The frame type marker identifying a control-channel frame. */
 declare const CONTROL: number
+/** The frame type marker identifying a user-data-channel frame. */
 declare const USER: number
+/** The default number of milliseconds a terminating worker gets to stop and exit. */
+declare const DEFAULT_GRACE: number
 
+/** The events emitted by a `Protocol`, in addition to the standard duplex stream events. */
 interface ProtocolEvents extends DuplexEvents {
+  /** Emitted when the worker signals it is ready. */
   ready: []
+  /** Emitted when a `terminate` control frame is received. */
   terminate: []
+  /** Emitted when the worker signals exit, carrying its exit `code`. */
   exit: [code: number]
 }
 
 interface Protocol<E extends ProtocolEvents = ProtocolEvents> extends Duplex<E> {
+  /**
+   * Send a control frame of `type` with an optional JSON-serializable `payload`.
+   * @param type - The control frame type, for example `'ready'`, `'exit'`, `'error'`, or
+   * `'terminate'`.
+   * @param payload - An optional JSON-serializable payload carried with the frame.
+   */
   send(type: string, payload?: object): Promise<void>
 }
 
 declare class Protocol {
+  /**
+   * Attach a `Protocol` to the given underlying duplex byte `stream`.
+   * @param stream - The underlying duplex byte stream to multiplex the control and user-data
+   * channels over.
+   */
   constructor(stream: Duplex)
 }
 
+/**
+ * Attach a `Protocol` to `stream`, an underlying duplex byte stream.
+ * @param stream - Any duplex byte stream to attach the protocol to.
+ * @returns A `Protocol` multiplexing control and user-data frames over `stream`.
+ */
 declare function attach(stream: Duplex): Protocol
 
-export { type Protocol, ProtocolEvents, attach, CONTROL, USER }
+export { type Protocol, ProtocolEvents, attach, CONTROL, USER, DEFAULT_GRACE }

package/lib/protocol.js

@@ -7,6 +7,8 @@ const USER = 0x01
 exports.CONTROL = CONTROL
 exports.USER = USER
 
+exports.DEFAULT_GRACE = 5000
+
 const HEADER_LENGTH = 5
 
 class Protocol extends Duplex {
@@ -22,7 +24,7 @@ class Protocol extends Duplex {
       .on('data', (chunk) => this._ondata(chunk))
       .on('end', () => this.push(null))
       .on('close', () => this.destroy())
-      .on('error', (err) => this.destroy(err))
+      .on('error', (err) => this._onerror(err))
   }
 
   send(type, payload) {
@@ -48,6 +50,13 @@ class Protocol extends Duplex {
     cb(null)
   }
 
+  _onerror(err) {
+    // On Linux, a peer that goes away with data still unread resets the
+    // connection rather than ending it, which is no different from it closing.
+    if (err.code === 'ECONNRESET') this.destroy()
+    else this.destroy(err)
+  }
+
   _ondata(chunk) {
     this._buffer.push(chunk)
     this._buffered += chunk.byteLength

package/lib/runtime.d.ts

@@ -0,0 +1,29 @@
+import { Duplex } from 'bare-stream'
+import { Protocol } from './protocol'
+
+interface Runtime extends Protocol {
+  /**
+   * Load the bundle entry and start it with `arg`, signaling ready once its `start()` resolves.
+   * @param load - A function importing the bundle entry module.
+   * @param arg - The value passed to the entry's `start()`.
+   */
+  run(load: () => Promise<{ default: Function }>, arg: unknown): Promise<void>
+}
+
+declare class Runtime {
+  /**
+   * Attach the worker side of a stowed bundle's lifecycle to `stream`.
+   * @param stream - The worker side of a stowed bundle's transport, typically `Bare.IPC`.
+   */
+  constructor(stream: Duplex)
+}
+
+/**
+ * Attach the worker side of a stowed bundle's lifecycle to `stream`, shutting the worker down on
+ * `terminate`, `SIGTERM`, runtime exit, uncaught errors, or loss of the host.
+ * @param stream - The worker side of a stowed bundle's transport, typically `Bare.IPC`.
+ * @returns A `Runtime` multiplexing control and user-data frames over `stream`.
+ */
+declare function attach(stream: Duplex): Runtime
+
+export { Runtime, attach }

package/lib/runtime.js

@@ -0,0 +1,92 @@
+const { Protocol, DEFAULT_GRACE } = require('./protocol')
+
+class Runtime extends Protocol {
+  constructor(stream) {
+    super(stream)
+
+    this._stop = null
+    this._grace = DEFAULT_GRACE
+    this._readied = false
+    this._exitCode = null
+    this._connected = true
+
+    const ondisconnect = () => this._ondisconnect()
+
+    this.on('configure', ({ grace }) => {
+      this._grace = grace
+    }).on('terminate', () => this._shutdown(0))
+
+    stream.on('end', ondisconnect).on('close', ondisconnect)
+
+    Bare.on('beforeExit', (code) => this._shutdown(code))
+      .on('uncaughtException', (err) => this._shutdown(1, err))
+      .on('unhandledRejection', (err) => this._shutdown(1, err))
+
+    // Signals are delivered to the whole process, so a worker thread must leave
+    // them to the host.
+    if (Bare.Thread.isMainThread) {
+      const Signal = require('bare-signals')
+
+      new Signal('SIGTERM')
+        .on('signal', () => this._onsigterm())
+        .start()
+        .unref()
+    }
+  }
+
+  async run(load, arg) {
+    try {
+      const entry = await load()
+
+      this._stop = await entry.default(arg, () => this._ready())
+
+      this._ready()
+    } catch (err) {
+      this._shutdown(1, err)
+    }
+  }
+
+  _ready() {
+    if (this._readied) return
+    this._readied = true
+
+    this.send('ready')
+  }
+
+  async _shutdown(code, err = null) {
+    if (this._exitCode !== null) return
+    this._exitCode = code
+
+    setTimeout(() => Bare.exit(code), this._grace).unref()
+
+    try {
+      if (this._stop) await this._stop()
+    } catch (e) {
+      err = err || e
+    }
+
+    if (this._connected) {
+      if (err) this.send('error', { message: err.message, stack: err.stack })
+
+      await this.send('exit', { code })
+    }
+
+    Bare.exit(code)
+  }
+
+  _ondisconnect() {
+    this._connected = false
+    this._shutdown(0)
+  }
+
+  _onsigterm() {
+    if (this._exitCode !== null) Bare.exit(this._exitCode)
+    else this._shutdown(0)
+  }
+}
+
+exports.Runtime = Runtime
+
+exports.attach = function attach(stream) {
+  return new Runtime(stream)
+}

package/lib/shim.js

@@ -9,60 +9,14 @@ module.exports = exports = function shim(entry, shimURL, opts = {}) {
 
   const specifier = relativeSpecifier(shimURL, entry)
 
-  const setup = server
-
-  const arg = setup ? '{ rpc, ipc }' : 'ipc'
+  const arg = server ? '{ rpc, ipc }' : 'ipc'
 
   return `\
-import protocol from 'bare-stow/protocol'
-
-const ipc = protocol.attach(Bare.IPC)
-${setup ? '\n' + setup : ''}
-let stop = null
-let readied = false
-let exited = false
-
-function ready() {
-  if (readied) return
-  readied = true
-
-  ipc.send('ready')
-}
-
-async function shutdown(code, err = null) {
-  if (exited) return
-  exited = true
-
-  try {
-    if (stop) await stop()
-  } catch (e) {
-    err = err || e
-  }
-
-  if (err) ipc.send('error', { message: err.message, stack: err.stack })
+import runtime from 'bare-stow/runtime'
 
-  await ipc.send('exit', { code })
-
-  Bare.exit(code)
-}
-
-ipc.on('terminate', () => shutdown(0))
-
-Bare
-  .on('beforeExit', (exitCode) => shutdown(exitCode))
-  .on('uncaughtException', (err) => shutdown(1, err))
-  .on('unhandledRejection', (err) => shutdown(1, err))
-
-try {
-  const entry = await import(${JSON.stringify(specifier)})
-  const start = entry.default
-
-  stop = await start(${arg}, ready) || null
-
-  ready()
-} catch (err) {
-  shutdown(1, err)
-}
+const ipc = runtime.attach(Bare.IPC)
+${server ? '\n' + server : ''}
+ipc.run(() => import(${JSON.stringify(specifier)}), ${arg})
 `
 }
 

package/lib/target/bare-sidecar.js

@@ -28,14 +28,13 @@ exports.generate = function generate(opts) {
     ? `\
 import Sidecar from 'bare-sidecar'
 import stow from 'bare-stow/host'
-import { fileURLToPath } from 'url'
 
-const bundle = fileURLToPath(new URL(${JSON.stringify(bundleSpecifier)}, import.meta.url))
+const bundle = new URL(import.meta.resolve(${JSON.stringify(bundleSpecifier)}))
 
-export async function start(opts = {}) {
+export async function start({ timeout, grace, ...opts } = {}) {
   const sidecar = new Sidecar(bundle, { stdio: 'inherit', ...opts })
 
-  const ${ipc} = stow.wrap(sidecar)
+  const ${ipc} = stow.wrap(sidecar, { timeout, grace })
 ${client ? '\n' + indent(client.source, 2) : ''}
   await ${ipc}.ready
 
@@ -43,17 +42,16 @@ ${client ? '\n' + indent(client.source, 2) : ''}
 }
 `
     : `\
-const path = require('path')
 const Sidecar = require('bare-sidecar')
 const stow = require('bare-stow/host')
 
-const bundle = path.join(__dirname, ${JSON.stringify(bundleSpecifier)})
+const bundle = require.resolve(${JSON.stringify(bundleSpecifier)})
 
 module.exports = {
-  async start(opts = {}) {
+  async start({ timeout, grace, ...opts } = {}) {
     const sidecar = new Sidecar(bundle, { stdio: 'inherit', ...opts })
 
-    const ${ipc} = stow.wrap(sidecar)
+    const ${ipc} = stow.wrap(sidecar, { timeout, grace })
 ${client ? '\n' + indent(client.source, 4) : ''}
     await ${ipc}.ready
 
@@ -67,7 +65,9 @@ ${client ? '\n' + indent(client.source, 4) : ''}
     {
       extension: '.d.ts',
       source: `\
-export function start(opts?: import('bare-sidecar').SidecarOptions): Promise<${handle}>
+export function start(
+  opts?: import('bare-sidecar').SidecarOptions & Omit<import('bare-stow/host').IPCOptions, 'kill'>
+): Promise<${handle}>
 `
     }
   ]

package/lib/target/bare-worker.js

@@ -28,14 +28,16 @@ exports.generate = function generate(opts) {
     ? `\
 import Worker from 'bare-worker'
 import stow from 'bare-stow/host'
-import { fileURLToPath } from 'bare-url'
 
-const bundle = fileURLToPath(new URL(${JSON.stringify(bundleSpecifier)}, import.meta.url))
+const bundle = import.meta.resolve(${JSON.stringify(bundleSpecifier)})
 
-export async function start(opts = {}) {
+export async function start({ timeout, grace, ...opts } = {}) {
   const worker = new Worker(bundle, opts)
 
-  const ${ipc} = stow.wrap(worker.IPC)
+  const ${ipc} = stow.wrap(worker.IPC, { kill: () => worker.terminate(), timeout, grace })
+
+  // The IPC stream of a worker ends, but never closes, when its thread exits.
+  worker.IPC.on('end', () => worker.IPC.destroy())
 ${client ? '\n' + indent(client.source, 2) : ''}
   await ${ipc}.ready
 
@@ -43,17 +45,19 @@ ${client ? '\n' + indent(client.source, 2) : ''}
 }
 `
     : `\
-const path = require('bare-path')
 const Worker = require('bare-worker')
 const stow = require('bare-stow/host')
 
-const bundle = path.join(__dirname, ${JSON.stringify(bundleSpecifier)})
+const bundle = require.resolve(${JSON.stringify(bundleSpecifier)})
 
 module.exports = {
-  async start(opts = {}) {
+  async start({ timeout, grace, ...opts } = {}) {
     const worker = new Worker(bundle, opts)
 
-    const ${ipc} = stow.wrap(worker.IPC)
+    const ${ipc} = stow.wrap(worker.IPC, { kill: () => worker.terminate(), timeout, grace })
+
+    // The IPC stream of a worker ends, but never closes, when its thread exits.
+    worker.IPC.on('end', () => worker.IPC.destroy())
 ${client ? '\n' + indent(client.source, 4) : ''}
     await ${ipc}.ready
 
@@ -67,7 +71,9 @@ ${client ? '\n' + indent(client.source, 4) : ''}
     {
       extension: '.d.ts',
       source: `\
-export function start(opts?: import('bare-worker').WorkerOptions): Promise<${handle}>
+export function start(
+  opts?: import('bare-worker').WorkerOptions & Omit<import('bare-stow/host').IPCOptions, 'kill'>
+): Promise<${handle}>
 `
     }
   ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-stow",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Module bundling and harness generation for Bare",
   "exports": {
     "./package": "./package.json",
@@ -15,6 +15,10 @@
     "./host": {
       "types": "./lib/host.d.ts",
       "default": "./lib/host.js"
+    },
+    "./runtime": {
+      "types": "./lib/runtime.d.ts",
+      "default": "./lib/runtime.js"
     }
   },
   "imports": {
@@ -68,15 +72,16 @@
     "bare-fs": "^4.2.1",
     "bare-module-lexer": "^1.6.0",
     "bare-module-traverse": "^2.2.0",
-    "bare-pack": "^2.2.0",
+    "bare-pack": "^3.0.0",
     "bare-path": "^3.0.0",
+    "bare-signals": "^5.0.0",
     "bare-stream": "^2.13.1",
     "bare-type-stripper": "^0.1.2",
     "paparam": "^1.5.0"
   },
   "devDependencies": {
     "bare-rpc": "^1.3.2",
-    "bare-sidecar": "^0.5.8",
+    "bare-sidecar": "^0.5.9",
     "bare-worker": "^4.3.0",
     "brittle": "^4.0.2",
     "lunte": "^1.7.0",