bare-stow 0.1.9 → 0.2.0

package/lib/target/bare-worker.js

@@ -1,4 +1,7 @@
+const harness = require('./javascript')
+
 exports.name = 'bare-worker'
+exports.isolation = 'thread'
 exports.linked = false
 exports.offload = true
 exports.format = 'bundle'
@@ -13,80 +16,23 @@ exports.hosts = [
   'win32-x64'
 ]
 
-exports.generate = function generate(opts) {
-  const { bundleSpecifier, ipc, rpc, module = 'cjs', client = null } = opts
-
-  const esm = module === 'esm'
-
-  const returned = client ? `{ ${ipc}, ${rpc} }` : `{ ${ipc} }`
-
-  const handle = client
-    ? `{ ${ipc}: import('bare-stow/host').IPC; ${rpc}: ${client.type} }`
-    : `{ ${ipc}: import('bare-stow/host').IPC }`
-
-  const source = esm
-    ? `\
-import Worker from 'bare-worker'
-import stow from 'bare-stow/host'
-
-const bundle = import.meta.resolve(${JSON.stringify(bundleSpecifier)})
+exports.languages = {
+  javascript: {
+    generate(context) {
+      return harness(context, {
+        name: 'bare-worker',
+        version: '^4.3.0',
+        binding: 'Worker',
+        setup: `\
+const worker = new Worker(bundle, opts)
 
-export async function start({ timeout, grace, ...opts } = {}) {
-  const worker = new Worker(bundle, opts)
-
-  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())
-
-  worker.on('exit', (code) => ${ipc}.exited(code))
-${client ? '\n' + indent(client.source, 2) : ''}
-  await ${ipc}.ready
-
-  return ${returned}
-}
-`
-    : `\
-const Worker = require('bare-worker')
-const stow = require('bare-stow/host')
+const ipc = stow.wrap(worker.IPC, { kill: () => worker.terminate(), timeout, grace })
 
-const bundle = require.resolve(${JSON.stringify(bundleSpecifier)})
+worker.IPC.on('end', () => worker.IPC.destroy())
 
-module.exports = {
-  async start({ timeout, grace, ...opts } = {}) {
-    const worker = new Worker(bundle, opts)
-
-    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())
-
-    worker.on('exit', (code) => ${ipc}.exited(code))
-${client ? '\n' + indent(client.source, 4) : ''}
-    await ${ipc}.ready
-
-    return ${returned}
-  }
-}
-`
-
-  return [
-    { source },
-    {
-      extension: '.d.ts',
-      source: `\
-export function start(
-  opts?: import('bare-worker').WorkerOptions & Omit<import('bare-stow/host').IPCOptions, 'kill'>
-): Promise<${handle}>
-`
+worker.on('exit', (code) => ipc.exited(code))`,
+        types: "import('bare-worker').WorkerOptions"
+      })
     }
-  ]
-}
-
-function indent(source, spaces) {
-  const pad = ' '.repeat(spaces)
-  return source
-    .split('\n')
-    .map((line) => (line.length === 0 ? line : pad + line))
-    .join('\n')
+  }
 }

package/lib/target/javascript.js

@@ -0,0 +1,63 @@
+module.exports = function harness(context, target) {
+  const { bundle, client, options } = context
+  const { name, version, binding, url = false, setup, types } = target
+
+  const esm = options.module === 'esm'
+
+  const body = `\
+${setup}
+${client ? '\nconst rpc = client.attach(ipc, handlers)\n' : ''}
+await ipc.ready
+
+return ${client ? '{ ipc, rpc }' : '{ ipc }'}`
+
+  const source = esm
+    ? `\
+import ${binding} from '${name}'
+import stow from 'bare-stow-host'
+${client ? `import * as client from ${JSON.stringify(client)}\n` : ''}
+const bundle = ${url ? `new URL(import.meta.resolve(${JSON.stringify(bundle)}))` : `import.meta.resolve(${JSON.stringify(bundle)})`}
+
+export async function start({ timeout, grace, ${client ? 'handlers = () => {}, ' : ''}...opts } = {}) {
+${indent(body, 2)}
+}
+`
+    : `\
+const ${binding} = require('${name}')
+const stow = require('bare-stow-host')
+${client ? `const client = require(${JSON.stringify(client)})\n` : ''}
+const bundle = require.resolve(${JSON.stringify(bundle)})
+
+module.exports = {
+  async start({ timeout, grace, ${client ? 'handlers = () => {}, ' : ''}...opts } = {}) {
+${indent(body, 4)}
+  }
+}
+`
+
+  const handle = client
+    ? `{ ipc: import('bare-stow-host').IPC; rpc: ReturnType<typeof import(${JSON.stringify(client)}).attach> }`
+    : `{ ipc: import('bare-stow-host').IPC }`
+
+  return {
+    source,
+    dependencies: {
+      [name]: version,
+      'bare-stow-host': '^0.1.0'
+    },
+    types: `\
+export function start(
+  opts?: ${types} & Omit<import('bare-stow-host').IPCOptions, 'kill'>${client ? ` & { handlers?: import(${JSON.stringify(client)}).Handlers }` : ''}
+): Promise<${handle}>
+`
+  }
+}
+
+function indent(source, spaces) {
+  const pad = ' '.repeat(spaces)
+
+  return source
+    .split('\n')
+    .map((line) => (line.length === 0 ? line : pad + line))
+    .join('\n')
+}

package/lib/target/swift.js

@@ -0,0 +1,57 @@
+// The harness qualifies `BareStowHost.IPC` as runtimes such as Bare Kit declare
+// an `IPC` of their own.
+module.exports = function harness(context, target) {
+  const { bundle, client } = context
+  const { module, conformance, fields = {}, params = [], setup, dependencies } = target
+
+  const started = { ...fields, ipc: 'BareStowHost.IPC' }
+
+  if (client) started.rpc = 'Client'
+
+  const source = `\
+import ${module}
+import BareStowHost
+import Foundation
+
+${conformance}
+
+public struct Started: Sendable {
+${Object.entries(started)
+  .map(([name, type]) => `  public let ${name}: ${type}`)
+  .join('\n')}
+}
+
+public func start(
+${[
+  ...params,
+  'timeout: TimeInterval? = nil',
+  'grace: TimeInterval = BareStowHost.IPC.defaultGrace',
+  ...(client ? ['handlers: Handlers? = nil'] : [])
+]
+  .map((param) => '  ' + param)
+  .join(',\n')}
+) async throws -> Started {
+  let bundle = Bundle.module.url(forResource: ${JSON.stringify(bundle)}, withExtension: nil)!
+
+${setup.replace(/^(?=.)/gm, '  ')}
+${client ? '\n  let rpc = attach(ipc, handlers)\n' : ''}
+  try await ipc.ready()
+
+  return Started(${Object.keys(started)
+    .map((name) => `${name}: ${name}`)
+    .join(', ')})
+}
+`
+
+  return {
+    source,
+    dependencies: {
+      ...dependencies,
+      'bare-stow-host-swift': {
+        url: 'https://github.com/holepunchto/bare-stow-host-swift',
+        from: '0.1.0',
+        products: ['BareStowHost']
+      }
+    }
+  }
+}

package/lib/target.js

@@ -1,28 +1,59 @@
-const registry = {
+const { registry, validateLanguages } = require('./provider')
+
+const providers = {
+  'bare-kit': () => require('./target/bare-kit'),
   'bare-sidecar': () => require('./target/bare-sidecar'),
   'bare-worker': () => require('./target/bare-worker')
 }
 
-module.exports = function target(name, resolve) {
-  if (typeof name !== 'string') return validate(name)
+const properties = [
+  'isolation',
+  'linked',
+  'linking',
+  'offload',
+  'format',
+  'encoding',
+  'extension',
+  'hosts'
+]
 
-  const load = registry[name]
+module.exports = registry('target', providers, function validate(target) {
+  validateLanguages('Target', target?.languages)
 
-  if (load) return load()
+  return target
+})
 
-  if (resolve) return validate(resolve(name))
+module.exports.options = function options(target, given = {}) {
+  if (typeof target.options === 'function') return target.options(given)
 
-  throw new Error(`Unknown target '${name}'`)
+  for (const option of Object.keys(given)) {
+    throw new Error(`Unknown option '${option}' for target '${target.name}'`)
+  }
+
+  return {}
 }
 
-function validate(target) {
-  if (!target || typeof target.generate !== 'function') {
-    throw new Error('Target must provide a generate() function')
+// A property may instead be a function of the language of the harness, the
+// options it resolved, and the options of the target, such as hosts that differ
+// between languages.
+module.exports.resolve = function resolve(target, context) {
+  const resolved = { linking: 'package', ...target }
+
+  for (const property of properties) {
+    if (typeof target[property] === 'function') resolved[property] = target[property](context)
   }
 
-  if (!Array.isArray(target.hosts)) {
+  if (resolved.isolation !== 'process' && resolved.isolation !== 'thread') {
+    throw new Error("Target must provide an isolation of 'process' or 'thread'")
+  }
+
+  if (resolved.linking !== 'package' && resolved.linking !== 'app') {
+    throw new Error("Target must provide a linking of 'package' or 'app'")
+  }
+
+  if (!Array.isArray(resolved.hosts)) {
     throw new Error('Target must provide a hosts array')
   }
 
-  return target
+  return resolved
 }

package/package.json

@@ -1,24 +1,12 @@
 {
   "name": "bare-stow",
-  "version": "0.1.9",
+  "version": "0.2.0",
   "description": "Module bundling and harness generation for Bare",
   "exports": {
     "./package": "./package.json",
     ".": {
       "types": "./index.d.ts",
       "default": "./index.js"
-    },
-    "./protocol": {
-      "types": "./lib/protocol.d.ts",
-      "default": "./lib/protocol.js"
-    },
-    "./host": {
-      "types": "./lib/host.d.ts",
-      "default": "./lib/host.js"
-    },
-    "./runtime": {
-      "types": "./lib/runtime.d.ts",
-      "default": "./lib/runtime.js"
     }
   },
   "imports": {
@@ -66,23 +54,23 @@
   },
   "homepage": "https://github.com/holepunchto/bare-stow#readme",
   "dependencies": {
-    "b4a": "^1.6.0",
     "bare-bundle": "^1.8.3",
     "bare-bundle-id": "^1.0.0",
     "bare-fs": "^4.2.1",
-    "bare-module-lexer": "^1.6.0",
+    "bare-link": "^4.1.0",
     "bare-module-traverse": "^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",
+    "bare-unpack": "^1.1.3",
     "paparam": "^1.5.0"
   },
   "devDependencies": {
     "bare-os": "^3.0.0",
     "bare-rpc": "^1.3.2",
     "bare-sidecar": "^0.5.11",
+    "bare-stow-host": "^0.1.0",
+    "bare-stow-runtime": "^0.1.0",
     "bare-worker": "^4.3.0",
     "brittle": "^4.0.2",
     "lunte": "^1.7.0",
@@ -91,13 +79,9 @@
     "which-runtime": "^1.4.0"
   },
   "peerDependencies": {
-    "bare-buffer": "^3.6.0",
     "bare-url": "^2.4.0"
   },
   "peerDependenciesMeta": {
-    "bare-buffer": {
-      "optional": true
-    },
     "bare-url": {
       "optional": true
     }

package/lib/host.d.ts

@@ -1,64 +0,0 @@
-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>
-  /**
-   * Report that the worker has exited, as observed by the transport. If the worker exited without
-   * saying why and was not asked to, the handle is destroyed with an error carrying the reason as
-   * `exitCode` and `signalCode`.
-   * @param code - The exit code of the worker, or `null` if it was killed by a signal.
-   * @param signal - The signal that killed the worker, or `null` (default `null`).
-   */
-  exited(code: number | null, signal?: string | null): void
-}
-
-declare class IPC {
-  /**
-   * 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)
-}
-
-/**
- * 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 { IPC, type IPCOptions, wrap }

package/lib/host.js

@@ -1,114 +0,0 @@
-const { Protocol, DEFAULT_GRACE } = require('./protocol')
-
-class IPC extends Protocol {
-  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._exitReported = false
-
-    this.once('exit', () => {
-      this._exitReported = true
-    })
-
-    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 = () => {
-        cleanup()
-        resolve()
-      }
-
-      const onerror = (err) => {
-        cleanup()
-        reject(err)
-      }
-
-      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.destroy())
-  }
-
-  get ready() {
-    return this._ready
-  }
-
-  terminate() {
-    if (this._stream.destroyed) return Promise.resolve(undefined)
-
-    return new Promise((resolve) => {
-      this.once('exit', resolve)
-
-      this._terminate().then(() => {
-        this.off('exit', resolve)
-        resolve(undefined)
-      })
-    })
-  }
-
-  exited(code, signal = null) {
-    // The worker either said why it exited or was asked to.
-    if (this._exitReported || this._terminating !== null || this.destroying) return
-
-    const err = new Error(
-      signal === null ? `Worker exited with code ${code}` : `Worker was killed by ${signal}`
-    )
-
-    err.exitCode = code
-    err.signalCode = signal
-
-    this.destroy(err)
-  }
-
-  _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._terminating = new Promise((resolve) => {
-      this._stream.once('close', () => {
-        clearTimeout(timer)
-        resolve()
-      })
-    })
-
-    return this._terminating
-  }
-}
-
-exports.IPC = IPC
-
-exports.wrap = function wrap(stream, opts) {
-  return new IPC(stream, opts)
-}

package/lib/protocol.d.ts

@@ -1,46 +0,0 @@
-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, DEFAULT_GRACE }