bare-stow 0.3.0 → 0.3.2

package/README.md

@@ -69,6 +69,22 @@ The bundle imports `bare-stow-runtime`, and the RPC library if a `server` is req
 
 `start()` accepts `timeout`, how long to wait in milliseconds for the bundle to signal ready, and `grace`, how long a terminating bundle gets to run `stop()` and exit before it's killed. `timeout` defaults to waiting indefinitely and `grace` to 5 seconds. On Windows, a sidecar is killed along with its host, so `stop()` only runs when the host terminates it.
 
+For `bare-sidecar` and `bare-worker`, the harness also exports `connect()`, which takes a sidecar or worker that the host started itself, such as one running a development entry with arguments, and resolves like `start()`. It accepts the same options, except those of the sidecar or worker. As the entry doesn't go through `stow()`, it attaches to the IPC itself, as described in <https://github.com/holepunchto/bare-stow-runtime>:
+
+```js
+const runtime = require('bare-stow-runtime/process')
+
+const ipc = runtime.attach(Bare.IPC)
+
+ipc.run(() => import('./core.js'), ipc)
+```
+
+```js
+const sidecar = new Sidecar('./dev.js', ['--verbose'], { stdio: 'inherit' })
+
+const { ipc } = await harness.connect(sidecar)
+```
+
 `stow()` and `link()` read the module graph from disk by default. To read it from elsewhere, such as modules that aren't written to disk, pass `readModule`, `listPrefix`, and `resolveModule`. Generated files are still written to disk. A `readModule` that changes the type of a module also passes `aliases`, as for <https://github.com/holepunchto/bare-pack>, such as `{ '.mjs': '.js' }` to have ES modules converted to CommonJS loaded as such. They're merged over the aliases that `bare-stow` uses for TypeScript.
 
 ## Targets

package/lib/shim.js

@@ -1,28 +1,30 @@
 const javascript = require('./language/javascript')
 const { select } = require('./provider')
 
-// The bundle runs in Bare, so its side of every provider is JavaScript.
+// The bundle runs in Bare, so its side of every provider is JavaScript. The
+// shims are CommonJS, which loads in any graph, such as one whose ES modules are
+// converted to CommonJS.
 module.exports = function shim(entry, isolation, server = null) {
   if (server) server = select('RPC library', server, javascript.name)
 
   const dir = new URL('./', entry)
-  const url = new URL('__main__.mjs', dir)
-  const serverURL = server ? new URL('__server__.mjs', dir) : null
+  const url = new URL('__main__.cjs', dir)
+  const serverURL = server ? new URL('__server__.cjs', dir) : null
 
   const modules = new Map()
 
   if (server) {
     modules.set(
       serverURL.href,
-      server.generate({ role: 'server', options: { module: 'esm' } }).source
+      server.generate({ role: 'server', options: { module: 'cjs' } }).source
     )
   }
 
   modules.set(
     url.href,
     `\
-import runtime from '${isolation === 'process' ? 'bare-stow-runtime/process' : 'bare-stow-runtime'}'
-${server ? `import * as server from ${JSON.stringify(javascript.reference(url, serverURL))}\n` : ''}
+const runtime = require('${isolation === 'process' ? 'bare-stow-runtime/process' : 'bare-stow-runtime'}')
+${server ? `const server = require(${JSON.stringify(javascript.reference(url, serverURL))})\n` : ''}
 const ipc = runtime.attach(Bare.IPC)
 ${server ? '\nconst rpc = server.attach(ipc)\n' : ''}
 ipc.run(() => import(${JSON.stringify(javascript.reference(url, entry))}), ${server ? '{ rpc, ipc }' : 'ipc'})

package/lib/target/bare-sidecar.js

@@ -25,9 +25,9 @@ exports.languages = {
         version: '^0.5.15',
         binding: 'Sidecar',
         url: true,
-        setup: `\
-const sidecar = new Sidecar(bundle, { stdio: 'inherit', ...opts })
-
+        handle: 'sidecar',
+        spawn: "new Sidecar(bundle, { stdio: 'inherit', ...opts })",
+        connect: `\
 const ipc = stow.wrap(sidecar, { kill: () => sidecar.kill('SIGKILL'), timeout, grace })
 
 sidecar.on('exit', (code, signal) => ipc.exited(code, signal))`,
@@ -41,9 +41,9 @@ sidecar.on('exit', (code, signal) => ipc.exited(code, signal))`,
       return swift(context, {
         module: 'BareSidecar',
         conformance: 'extension Sidecar: @retroactive BareStowHost.Transport {}',
+        handle: { name: 'sidecar', type: 'Sidecar' },
+        spawn: 'try await Sidecar.spawn(bundle)',
         setup: `\
-let sidecar = try await Sidecar.spawn(bundle)
-
 let ipc = BareStowHost.IPC(sidecar, kill: { sidecar.kill() }, timeout: timeout, grace: grace)
 
 Task {
@@ -55,7 +55,7 @@ Task {
         dependencies: {
           'bare-sidecar-swift': {
             url: 'https://github.com/holepunchto/bare-sidecar-swift',
-            from: '0.1.2',
+            from: '0.1.3',
             products: ['BareSidecar']
           }
         }
@@ -70,7 +70,7 @@ import asyncio
 from pathlib import Path
 from typing import NamedTuple
 
-${client ? 'from bare_rpc import RPC\n' : ''}from bare_sidecar import spawn
+${client ? 'from bare_rpc import RPC\n' : ''}from bare_sidecar import Sidecar, spawn
 from bare_stow_host import DEFAULT_GRACE, IPC, wrap
 ${client ? `\nfrom ${client} import Handlers, attach\n` : ''}
 bundle = Path(__file__).parent / ${JSON.stringify(bundle)}
@@ -90,6 +90,15 @@ async def start(
 ) -> Started:
     sidecar = await spawn(bundle, **opts)
 
+    return await connect(sidecar, timeout=timeout, grace=grace${client ? ', handlers=handlers' : ''})
+
+
+async def connect(
+    sidecar: Sidecar,
+    *,
+    timeout=None,
+    grace=DEFAULT_GRACE,${client ? '\n    handlers: Handlers = lambda router: None,' : ''}
+) -> Started:
     ipc = wrap(sidecar, kill=sidecar.kill, timeout=timeout, grace=grace)
 
     watching = asyncio.ensure_future(_watch(sidecar, ipc))

package/lib/target/bare-worker.js

@@ -23,9 +23,9 @@ exports.languages = {
         name: 'bare-worker',
         version: '^4.5.3',
         binding: 'Worker',
-        setup: `\
-const worker = new Worker(bundle, opts)
-
+        handle: 'worker',
+        spawn: 'new Worker(bundle, opts)',
+        connect: `\
 const ipc = stow.wrap(worker.IPC, { kill: () => worker.terminate(), timeout, grace })
 
 worker.IPC.on('end', () => worker.IPC.destroy())

package/lib/target/javascript.js

@@ -1,11 +1,18 @@
 module.exports = function harness(context, target) {
   const { bundle, client, options } = context
-  const { name, version, binding, url = false, setup, types } = target
+  const { name, version, binding, url = false, handle, spawn, connect, types } = target
 
   const esm = options.module === 'esm'
 
+  const params = `{ timeout, grace${client ? ', handlers = () => {}' : ''} } = {}`
+
+  const start = `\
+const ${handle} = ${spawn}
+
+return await connect(${handle}, { timeout, grace${client ? ', handlers' : ''} })`
+
   const body = `\
-${setup}
+${connect}
 ${client ? '\nconst rpc = client.attach(ipc, handlers)\n' : ''}
 await ipc.ready
 
@@ -18,7 +25,11 @@ 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 } = {}) {
+export async function start({ timeout, grace, ${client ? 'handlers, ' : ''}...opts } = {}) {
+${indent(start, 2)}
+}
+
+export async function connect(${handle}, ${params}) {
 ${indent(body, 2)}
 }
 `
@@ -28,14 +39,18 @@ 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)}
-  }
+module.exports = { start, connect }
+
+async function start({ timeout, grace, ${client ? 'handlers, ' : ''}...opts } = {}) {
+${indent(start, 2)}
+}
+
+async function connect(${handle}, ${params}) {
+${indent(body, 2)}
 }
 `
 
-  const handle = client
+  const started = client
     ? `{ ipc: import('bare-stow-host').IPC; rpc: ReturnType<typeof import(${JSON.stringify(client)}).attach> }`
     : `{ ipc: import('bare-stow-host').IPC }`
 
@@ -46,9 +61,11 @@ ${indent(body, 4)}
       'bare-stow-host': '^0.2.0'
     },
     types: `\
-export function start(
-  opts?: ${types} & Omit<import('bare-stow-host').IPCOptions, 'kill'>${client ? ` & { handlers?: import(${JSON.stringify(client)}).Handlers }` : ''}
-): Promise<${handle}>
+type ConnectOptions = Omit<import('bare-stow-host').IPCOptions, 'kill'>${client ? ` & { handlers?: import(${JSON.stringify(client)}).Handlers }` : ''}
+
+export function start(opts?: ${types} & ConnectOptions): Promise<${started}>
+
+export function connect(${handle}: import('${name}'), opts?: ConnectOptions): Promise<${started}>
 `
   }
 }

package/lib/target/swift.js

@@ -2,12 +2,59 @@
 // an `IPC` of their own.
 module.exports = function harness(context, target) {
   const { bundle, client } = context
-  const { module, conformance, fields = {}, params = [], setup, dependencies } = target
+  const {
+    module,
+    conformance,
+    fields = {},
+    params = [],
+    handle,
+    spawn,
+    setup,
+    dependencies
+  } = target
 
   const started = { ...fields, ipc: 'BareStowHost.IPC' }
 
   if (client) started.rpc = 'RPC'
 
+  const options = [
+    'timeout: TimeInterval? = nil',
+    'grace: TimeInterval = BareStowHost.IPC.defaultGrace',
+    ...(client ? ['handlers: Handlers? = nil'] : [])
+  ]
+
+  const forwarded = ['timeout', 'grace', ...(client ? ['handlers'] : [])].map(
+    (name) => `${name}: ${name}`
+  )
+
+  const body = `\
+${setup}
+${client ? '\nlet rpc = attach(ipc, handlers)\n' : ''}
+try await ipc.ready()
+
+return Started(${Object.keys(started)
+    .map((name) => `${name}: ${name}`)
+    .join(', ')})`
+
+  const resource = `let bundle = Bundle.module.url(forResource: ${JSON.stringify(bundle)}, withExtension: nil)!`
+
+  // Targets that spawn the bundle let hosts connect to one they spawned, such
+  // as from another entry.
+  const start = handle
+    ? `\
+${resource}
+
+let ${handle.name} = ${spawn}
+
+return try await connect(${[handle.name, ...forwarded].join(', ')})`
+    : `${resource}\n\n${body}`
+
+  const functions = [func('start', [...params, ...options], start)]
+
+  if (handle) {
+    functions.push(func('connect', [`_ ${handle.name}: ${handle.type}`, ...options], body))
+  }
+
   const source = `\
 import ${module}
 ${client ? 'import BareRPC\n' : ''}import BareStowHost
@@ -21,26 +68,7 @@ ${Object.entries(started)
   .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(', ')})
-}
+${functions.join('\n\n')}
 `
 
   return {
@@ -55,3 +83,19 @@ ${client ? '\n  let rpc = attach(ipc, handlers)\n' : ''}
     }
   }
 }
+
+function func(name, params, body) {
+  return `\
+public func ${name}(
+${params.map((param) => '  ' + param).join(',\n')}
+) async throws -> Started {
+${indent(body)}
+}`
+}
+
+function indent(source) {
+  return source
+    .split('\n')
+    .map((line) => (line.length === 0 ? line : '  ' + line))
+    .join('\n')
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-stow",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Module bundling and harness generation for Bare",
   "exports": {
     "./package": "./package.json",