bare-stow 0.0.0 → 0.1.0

package/index.js

@@ -0,0 +1,207 @@
+const path = require('path')
+const { fileURLToPath } = require('url')
+const pack = require('bare-pack')
+const { resolve } = require('bare-module-traverse')
+const id = require('bare-bundle-id')
+const fs = require('./lib/fs')
+const shim = require('./lib/shim')
+const harness = require('./lib/target')
+const rpc = require('./lib/rpc')
+
+module.exports = async function* stow(entry, target, out, opts = {}) {
+  if (!target) throw new Error("'target' is required")
+  if (!out) throw new Error("'out' is required")
+
+  let { client, server, base, hosts, resolveTarget, resolveRPC, ...packOpts } = opts
+
+  const t = harness(target, resolveTarget)
+
+  const targetName = typeof target === 'string' ? target : t.name
+
+  entry = new URL(entry)
+  out = new URL(out)
+  base = base ? new URL(base) : new URL('./', entry)
+
+  if (hosts) {
+    for (const host of hosts) {
+      if (!t.hosts.includes(host)) {
+        throw new Error(`Host '${host}' is not supported by target '${targetName}'`)
+      }
+    }
+  } else {
+    hosts = t.hosts
+  }
+
+  const shimURL = shim.url(base)
+
+  // The server only contributes runtime wiring to the shim; the shim is not a
+  // typed, host-facing module so it has no declaration artifact.
+  const serverSetup = server
+    ? fragment(
+        rpc(server, resolveRPC).generate({
+          ipc: 'ipc',
+          rpc: 'rpc',
+          module: 'esm',
+          role: 'server'
+        }),
+        null
+      )
+    : null
+
+  const shimSource = shim(entry, shimURL, { server: serverSetup })
+
+  const readModule = wrapReadModule(fs.readModule, shimURL, shimSource)
+
+  const bundleURL = siblingURL(out, t.extension)
+  const bundleSpecifier = relativeSpecifier(out, bundleURL)
+
+  const offloaded = []
+
+  let writeFile
+
+  if (isOffloadEnabled(t.offload)) writeFile = collectOffloaded(base, out, offloaded)
+
+  const bundle = await pack(
+    shimURL,
+    {
+      resolve: resolve.bare,
+      ...packOpts,
+      hosts,
+      linked: t.linked,
+      offload: t.offload,
+      base: base
+    },
+    readModule,
+    fs.listPrefix,
+    writeFile
+  )
+
+  bundle.id = id(bundle).toString('hex')
+
+  // The client contributes both runtime wiring (spliced into the harness) and a
+  // type expression (spliced into the harness declaration), so it is resolved
+  // into both channels before handing it to the target.
+  let clientSetup = null
+
+  if (client) {
+    const artifacts = rpc(client, resolveRPC).generate({
+      ipc: 'ipc',
+      rpc: 'rpc',
+      module: t.module,
+      role: 'client'
+    })
+
+    clientSetup = {
+      source: fragment(artifacts, null),
+      type: fragment(artifacts, '.d.ts')
+    }
+  }
+
+  const artifacts = t.generate({
+    bundleSpecifier,
+    ipc: 'ipc',
+    rpc: 'rpc',
+    client: clientSetup
+  })
+
+  // 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) {
+    const url = artifact.extension ? siblingURL(out, artifact.extension) : out
+
+    await fs.writeFile(url, artifact.source)
+    yield { url }
+  }
+
+  await fs.writeFile(bundleURL, encodeBundle(bundle, t.format, t.encoding ?? 'utf8'))
+  yield { url: bundleURL }
+
+  for (const artifact of offloaded) {
+    await fs.writeFile(artifact.url, artifact.source)
+    yield { url: artifact.url }
+  }
+}
+
+function isOffloadEnabled(offload) {
+  if (offload === true) return true
+  if (offload && (offload.addons || offload.assets)) return true
+
+  return false
+}
+
+function wrapReadModule(readModule, shimURL, shimSource) {
+  return function (url) {
+    if (url.href === shimURL.href) return shimSource
+
+    return readModule(url)
+  }
+}
+
+function collectOffloaded(base, out, sink) {
+  const dir = new URL('./', out)
+
+  return function writeFile(url, source) {
+    let relative
+
+    const nm = url.pathname.indexOf('/node_modules/')
+
+    if (nm >= 0) {
+      relative = url.pathname.slice(nm + 1)
+    } else if (url.pathname.startsWith(base.pathname)) {
+      relative = url.pathname.slice(base.pathname.length)
+    } else {
+      relative = url.pathname.replace(/^\//, '')
+    }
+
+    sink.push({ url: new URL(relative, dir), source })
+
+    return null
+  }
+}
+
+function siblingURL(out, extension) {
+  const dir = new URL('./', out)
+  const base = path.basename(out.pathname, path.extname(out.pathname))
+
+  return new URL(base + extension, dir)
+}
+
+function fragment(artifacts, extension) {
+  for (const artifact of artifacts) {
+    if ((artifact.extension ?? null) === extension) return artifact.source
+  }
+
+  return null
+}
+
+function relativeSpecifier(from, to) {
+  if (from.protocol === 'file:' && to.protocol === 'file:') {
+    const fromDir = path.dirname(fileURLToPath(from))
+    const toPath = fileURLToPath(to)
+
+    let relative = path.relative(fromDir, toPath).split(path.sep).join('/')
+
+    if (!relative.startsWith('.')) relative = './' + relative
+
+    return relative
+  }
+
+  return to.href
+}
+
+function encodeBundle(bundle, format, encoding) {
+  const data = bundle.toBuffer()
+
+  switch (format) {
+    case 'bundle':
+      return data
+    case 'bundle.cjs':
+      return `module.exports = ${JSON.stringify(data.toString(encoding))}\n`
+    case 'bundle.mjs':
+      return `export default ${JSON.stringify(data.toString(encoding))}\n`
+    case 'bundle.json':
+      return JSON.stringify(data.toString(encoding)) + '\n'
+    default:
+      throw new Error(`Unknown format '${format}'`)
+  }
+}

package/lib/fs.js

@@ -0,0 +1,78 @@
+const { fileURLToPath } = require('url')
+const fs = require('fs')
+
+exports.writeFile = async function writeFile(url, data) {
+  await exports.makeDir(new URL('.', url))
+
+  return new Promise((resolve, reject) => {
+    fs.writeFile(fileURLToPath(url), data, (err) => {
+      err ? reject(err) : resolve()
+    })
+  })
+}
+
+exports.readFile = function readFile(url) {
+  return new Promise((resolve, reject) => {
+    fs.readFile(fileURLToPath(url), (err, data) => {
+      err ? reject(err) : resolve(data)
+    })
+  })
+}
+
+exports.makeDir = function makeDir(url) {
+  return new Promise((resolve, reject) => {
+    fs.mkdir(fileURLToPath(url), { recursive: true }, (err) => {
+      err ? reject(err) : resolve()
+    })
+  })
+}
+
+exports.openDir = function openDir(url) {
+  return new Promise((resolve, reject) => {
+    fs.opendir(fileURLToPath(url), (err, dir) => {
+      err ? reject(err) : resolve(dir)
+    })
+  })
+}
+
+exports.readModule = async function readModule(url) {
+  try {
+    return await exports.readFile(url)
+  } catch {
+    return null
+  }
+}
+
+function isFile(url) {
+  return new Promise((resolve) => {
+    fs.stat(fileURLToPath(url), (err, stat) => {
+      resolve(err === null && stat.isFile())
+    })
+  })
+}
+
+function isDir(url) {
+  return new Promise((resolve) => {
+    fs.stat(fileURLToPath(url), (err, stat) => {
+      resolve(err === null && stat.isDirectory())
+    })
+  })
+}
+
+exports.listPrefix = async function* listPrefix(url) {
+  if (await isFile(url)) return yield url
+
+  if (url.pathname[url.pathname.length - 1] !== '/') {
+    url.pathname += '/'
+  }
+
+  if (await isDir(url)) {
+    for await (const entry of await exports.openDir(url)) {
+      if (entry.isDirectory()) {
+        yield* listPrefix(new URL(entry.name, url))
+      } else {
+        yield new URL(entry.name, url)
+      }
+    }
+  }
+}

package/lib/host.d.ts

@@ -0,0 +1,19 @@
+import { Duplex } from 'bare-stream'
+import { Protocol } from './protocol'
+
+interface IPC extends Protocol {
+  readonly ready: Promise<void>
+  terminate(): Promise<number | undefined>
+}
+
+declare class IPC {
+  constructor(stream: Duplex)
+}
+
+declare function wrap(stream: Duplex): IPC
+
+declare namespace wrap {
+  export { IPC }
+}
+
+export = wrap

package/lib/host.js

@@ -0,0 +1,62 @@
+const { Protocol } = require('./protocol')
+
+class IPC extends Protocol {
+  constructor(stream) {
+    super(stream)
+
+    this._ready = new Promise((resolve, reject) => {
+      const onready = () => {
+        this.off('ready', onready).off('error', onerror)
+        resolve()
+      }
+
+      const onerror = (err) => {
+        this.off('ready', onready).off('error', onerror)
+        reject(err)
+      }
+
+      this.on('ready', onready).on('error', onerror)
+    })
+
+    this._ready.catch(() => {})
+  }
+
+  get ready() {
+    return this._ready
+  }
+
+  terminate() {
+    return new Promise((resolve) => {
+      const cleanup = () => {
+        this.off('exit', onexit)
+        this._stream.off('close', onclose)
+      }
+
+      const onexit = (code) => {
+        cleanup()
+        resolve(code)
+      }
+
+      const onclose = () => {
+        cleanup()
+        resolve(undefined)
+      }
+
+      this.once('exit', onexit).send('terminate')
+      this._stream.once('close', onclose)
+    })
+  }
+
+  _destroy(err, cb) {
+    if (this._stream.destroyed) return cb(null)
+
+    this.send('terminate')
+    this._stream.once('close', () => cb(null))
+  }
+}
+
+exports.IPC = IPC
+
+exports.wrap = function wrap(stream) {
+  return new IPC(stream)
+}

package/lib/protocol.d.ts

@@ -0,0 +1,16 @@
+import { Duplex } from 'bare-stream'
+
+declare const CONTROL: number
+declare const USER: number
+
+interface Protocol extends Duplex {
+  send(type: string, payload?: object): Promise<void>
+}
+
+declare class Protocol {
+  constructor(stream: Duplex)
+}
+
+declare function attach(stream: Duplex): Protocol
+
+export { type Protocol, attach, CONTROL, USER }

package/lib/protocol.js

@@ -0,0 +1,129 @@
+const { Duplex, Writable } = require('bare-stream')
+
+const CONTROL = 0x00
+const USER = 0x01
+
+exports.CONTROL = CONTROL
+exports.USER = USER
+
+const HEADER_LENGTH = 5
+
+class Protocol extends Duplex {
+  constructor(stream) {
+    super()
+
+    this._stream = stream
+    this._buffer = []
+    this._buffered = 0
+    this._frame = -1
+
+    stream
+      .on('data', (chunk) => this._ondata(chunk))
+      .on('end', () => this.push(null))
+      .on('close', () => this.destroy())
+      .on('error', (err) => this.destroy(err))
+  }
+
+  send(type, payload) {
+    const frame = encodeFrame(CONTROL, Buffer.from(JSON.stringify({ type, ...payload })))
+
+    this._stream.write(frame)
+
+    return Writable.drained(this._stream)
+  }
+
+  _write(data, encoding, cb) {
+    const frame = encodeFrame(USER, data)
+
+    const ok = this._stream.write(frame)
+
+    if (ok) return cb(null)
+
+    this._stream.once('drain', () => cb(null))
+  }
+
+  _destroy(err, cb) {
+    this._stream.destroy()
+    cb(null)
+  }
+
+  _ondata(chunk) {
+    this._buffer.push(chunk)
+    this._buffered += chunk.byteLength
+
+    if (this._frame === -1) this._onbeforeframe()
+    else this._onafterframe()
+  }
+
+  _onbeforeframe() {
+    if (this._buffered < 4) return
+
+    const buffer = this._buffer.length === 1 ? this._buffer[0] : Buffer.concat(this._buffer)
+
+    this._buffer = [buffer]
+    this._frame = 4 + buffer.readUInt32LE(0)
+
+    this._onafterframe()
+  }
+
+  _onafterframe() {
+    if (this._buffered < this._frame) return
+
+    const buffer = this._buffer.length === 1 ? this._buffer[0] : Buffer.concat(this._buffer)
+    const frame = this._frame
+
+    this._buffered -= frame
+    this._buffer = this._buffered > 0 ? [buffer.subarray(frame)] : []
+    this._frame = -1
+
+    this._onframe(buffer.subarray(0, frame))
+    this._onbeforeframe()
+  }
+
+  _onframe(frame) {
+    const tag = frame.readUInt8(4)
+    const payload = frame.subarray(HEADER_LENGTH)
+
+    if (tag === USER) {
+      this.push(Buffer.from(payload))
+    } else if (tag === CONTROL) {
+      let message
+
+      try {
+        message = JSON.parse(payload.toString())
+      } catch {
+        return
+      }
+
+      if (message.type === 'error') {
+        const err = new Error(message.message)
+
+        if (message.stack) err.stack = message.stack
+
+        this.destroy(err)
+      } else if (message.type === 'exit') {
+        this.emit('exit', message.code)
+      } else {
+        this.emit(message.type, message)
+      }
+    }
+  }
+}
+
+exports.Protocol = Protocol
+
+exports.attach = function attach(stream) {
+  return new Protocol(stream)
+}
+
+function encodeFrame(tag, data) {
+  const length = data.length + 1
+  const frame = Buffer.alloc(HEADER_LENGTH + data.length)
+
+  frame.writeUInt32LE(length, 0)
+  frame.writeUInt8(tag, 4)
+
+  data.copy(frame, HEADER_LENGTH)
+
+  return frame
+}

package/lib/rpc/bare-rpc.js

@@ -0,0 +1,24 @@
+exports.name = 'bare-rpc'
+
+exports.generate = function generate(opts) {
+  const { ipc, rpc } = opts
+
+  const esm = opts.module === 'esm'
+
+  return [
+    {
+      source: `\
+${esm ? "const { default: RPC } = await import('bare-rpc')" : "const RPC = require('bare-rpc')"}
+
+const router = new RPC.CommandRouter()
+const ${rpc} = new RPC(${ipc}, router)
+
+${rpc}.respond = router.respond.bind(router)
+`
+    },
+    {
+      extension: '.d.ts',
+      source: "import('bare-rpc')"
+    }
+  ]
+}

package/lib/rpc.js

@@ -0,0 +1,23 @@
+const registry = {
+  'bare-rpc': () => require('./rpc/bare-rpc')
+}
+
+module.exports = function rpc(name, resolve) {
+  if (typeof name !== 'string') return validate(name)
+
+  const load = registry[name]
+
+  if (load) return load()
+
+  if (resolve) return validate(resolve(name))
+
+  throw new Error(`Unknown RPC library '${name}'`)
+}
+
+function validate(rpc) {
+  if (!rpc || typeof rpc.generate !== 'function') {
+    throw new Error('RPC library must provide a generate() function')
+  }
+
+  return rpc
+}

package/lib/shim.js

@@ -0,0 +1,86 @@
+const path = require('path')
+const { fileURLToPath } = require('url')
+
+module.exports = exports = function shim(entry, shimURL, opts = {}) {
+  // `server` is a pre-rendered RPC server setup fragment (binding `rpc`), or
+  // null. The bundler resolves the RPC library and renders it; the shim only
+  // decides where the fragment goes.
+  const { server = null } = opts
+
+  const specifier = relativeSpecifier(shimURL, entry)
+
+  const setup = server
+
+  const arg = setup ? '{ 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 })
+
+  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)
+}
+`
+}
+
+exports.url = function url(base) {
+  return new URL('__main__.mjs', base)
+}
+
+function relativeSpecifier(from, to) {
+  if (from.protocol === 'file:' && to.protocol === 'file:') {
+    const fromPath = path.dirname(fileURLToPath(from))
+    const toPath = fileURLToPath(to)
+
+    let relative = path.relative(fromPath, toPath).split(path.sep).join('/')
+
+    if (!relative.startsWith('.')) relative = './' + relative
+
+    return relative
+  }
+
+  return to.href
+}

package/lib/target/bare-sidecar.js

@@ -0,0 +1,63 @@
+exports.name = 'bare-sidecar'
+exports.linked = false
+exports.offload = true
+exports.format = 'bundle'
+exports.encoding = null
+exports.extension = '.bundle'
+exports.module = 'cjs'
+exports.hosts = [
+  'darwin-arm64',
+  'darwin-x64',
+  'linux-arm64',
+  'linux-x64',
+  'win32-arm64',
+  'win32-x64'
+]
+
+exports.generate = function generate(opts) {
+  const { bundleSpecifier, ipc, rpc, client = null } = opts
+
+  const returned = client ? `{ ${ipc}, ${rpc} }` : `{ ${ipc} }`
+
+  const handle = client
+    ? `{ ${ipc}: import('bare-stow/host').IPC; ${rpc}: ${client.type} }`
+    : `{ ${ipc}: import('bare-stow/host').IPC }`
+
+  return [
+    {
+      source: `\
+const path = require('path')
+const Sidecar = require('bare-sidecar')
+const stow = require('bare-stow/host')
+
+const bundle = path.join(__dirname, ${JSON.stringify(bundleSpecifier)})
+
+module.exports = {
+  async start(opts = {}) {
+    const sidecar = new Sidecar(bundle, opts)
+
+    const ${ipc} = stow.wrap(sidecar)
+${client ? '\n' + indent(client.source, 4) : ''}
+    await ${ipc}.ready
+
+    return ${returned}
+  }
+}
+`
+    },
+    {
+      extension: '.d.ts',
+      source: `\
+export function start(opts?: import('bare-sidecar').SidecarOptions): Promise<${handle}>
+`
+    }
+  ]
+}
+
+function indent(source, spaces) {
+  const pad = ' '.repeat(spaces)
+  return source
+    .split('\n')
+    .map((line) => (line.length === 0 ? line : pad + line))
+    .join('\n')
+}