Default module set (documented in docs/DEFAULT-MODULES.md):
CI / Build & Test (push) Successful in 8m10s
CI / Build & Test (push) Successful in 8m10s
Category Modules Runtime bare, bare-process, bare-module, bare-fs, bare-path, bare-stream Swarm / data hyperswarm, hypercore, corestore, hyperbee, hyperdrive, autobase, hyperdb, hyperschema, hrpc, protomux, compact-encoding, b4a Media bare-media, bare-ffmpeg, plus codecs via bare-media (jpeg/png/webp/gif/heif/…) Local power (bundled) bare-sqlite, bare-fetch
This commit is contained in:
Raven Scott
@@ -26,10 +26,9 @@ These are the main APIs your page uses. For host request types and event payload
|
||||
|
||||
- **`BridgeSwarm.request(type, payload, options)`** — Sends a request to the host. Optional third argument: `{ timeoutMs: number }` aborts after that many milliseconds and rejects with `"Request timed out after N ms"`. If the page does not pass `timeoutMs`, the extension’s **default request timeout** (from the options page) is used when it is > 0.
|
||||
|
||||
- **`BridgeSwarm.capabilities`** — Optional Bare capability packs on the host. `list()`, `has(pack)`, `call(pack, cmd, payload)`, `on(event, fn)`. See [CAPABILITIES.md](CAPABILITIES.md).
|
||||
|
||||
- **`BridgeSwarm.media.*`** — Media pack wrappers (`info`, `imageTransform`, `extractFrame`, `transcode`, `cancel`, `writeInput`, `readOutput`). Requires the media host artifact.
|
||||
- **`BridgeSwarm.capabilities`** — Bare capability packs on the host (`media` is default). `list()`, `has(pack)`, `call(pack, cmd, payload)`, `on(event, fn)`. See [CAPABILITIES.md](CAPABILITIES.md) / [DEFAULT-MODULES.md](DEFAULT-MODULES.md).
|
||||
|
||||
- **`BridgeSwarm.media.*`** — Media pack wrappers (`info`, `imageTransform`, `extractFrame`, `transcode`, `cancel`, `writeInput`, `readOutput`).
|
||||
---
|
||||
|
||||
## Host request types and events
|
||||
@@ -162,7 +161,8 @@ These events are broadcast to all subscribed tabs (no `swarmId` filter).
|
||||
## See also
|
||||
|
||||
- [DATA-API.md](DATA-API.md) — Data API details and examples.
|
||||
- [CAPABILITIES.md](CAPABILITIES.md) — Optional Bare capability packs (media, install, security).
|
||||
- [CAPABILITIES.md](CAPABILITIES.md) — Bare capability packs (media, security).
|
||||
- [DEFAULT-MODULES.md](DEFAULT-MODULES.md) — Modules in the default host (includes ffmpeg).
|
||||
- [HRPC.md](HRPC.md) — HRPC (attachHrpc) and commands.
|
||||
- [PROTOMUX.md](PROTOMUX.md) — Protomux in the browser and connection attachment.
|
||||
- [ARCHITECTURE.md](ARCHITECTURE.md) — Message flow and components.
|
||||
|
||||
+18
-44
@@ -1,19 +1,17 @@
|
||||
# Capabilities
|
||||
|
||||
BridgeSwarm exposes selected [Bare](https://github.com/holepunchto/bare) native APIs to the page as **optional capability packs**. The default host stays swarm/data-focused and does **not** ship heavy addons like `bare-ffmpeg` (~400+ MB unpacked).
|
||||
|
||||
Curated packs — not “every `bare-*` package” — is an intentional design choice.
|
||||
BridgeSwarm exposes selected [Bare](https://github.com/holepunchto/bare) native APIs to the page as **capability packs**. Curated packs — not every `bare-*` package — is intentional. The **default host includes media/`bare-ffmpeg`** plus other modules listed in [DEFAULT-MODULES.md](DEFAULT-MODULES.md).
|
||||
|
||||
## Page API
|
||||
|
||||
```js
|
||||
await BridgeSwarm.capabilities.list() // e.g. ['media'] or []
|
||||
await BridgeSwarm.capabilities.list() // e.g. ['media']
|
||||
await BridgeSwarm.capabilities.has('media')
|
||||
|
||||
// Generic dispatch
|
||||
await BridgeSwarm.capabilities.call('media', 'info', { path: '…' })
|
||||
|
||||
// Thin wrappers (Pack 1)
|
||||
// Thin wrappers
|
||||
await BridgeSwarm.media.info({ dataBase64, filename })
|
||||
await BridgeSwarm.media.imageTransform({ dataBase64, maxWidth: 640, mimetype: 'image/webp' })
|
||||
await BridgeSwarm.media.extractFrame({ dataBase64, frameIndex: 0 })
|
||||
@@ -31,23 +29,23 @@ Streaming results use host events (under the ~1 MB native-messaging limit):
|
||||
|
||||
`BridgeSwarm.media.*` helpers assign a `jobId`, listen for these events, and resolve with assembled `dataBase64` (or a host-relative `path` for large transcodes).
|
||||
|
||||
You can also subscribe manually:
|
||||
|
||||
```js
|
||||
const off = BridgeSwarm.capabilities.on('cap-chunk', (p) => console.log(p))
|
||||
```
|
||||
|
||||
## Security
|
||||
|
||||
Every pack that touches the filesystem is **allowlisted** under:
|
||||
Filesystem access for packs is **allowlisted** under:
|
||||
|
||||
```text
|
||||
$BRIDGE_SWARM_STORAGE/cap-jobs/
|
||||
```
|
||||
|
||||
(default: `~/.bridgeswarm/bridge-swarm-storage/cap-jobs/`). Absolute paths outside that tree are rejected. Large outputs are written there and returned as relative paths; the page can stream them back with `media.readOutput`.
|
||||
(default: `~/.bridgeswarm/bridge-swarm-storage/cap-jobs/`). Absolute paths outside that tree are rejected.
|
||||
|
||||
## Pack 1 — Media
|
||||
## Pack — Media (default)
|
||||
|
||||
Shipped in the standard `bridge-swarm-host` artifact (`bare-media` + `bare-ffmpeg` + image codecs).
|
||||
|
||||
| Command | Behavior |
|
||||
|---------|----------|
|
||||
@@ -58,23 +56,7 @@ $BRIDGE_SWARM_STORAGE/cap-jobs/
|
||||
| `media.cancel` | Cancel in-flight job |
|
||||
| `media.writeInput` / `media.readOutput` | Chunked upload / download under `cap-jobs/` |
|
||||
|
||||
### Install media host
|
||||
|
||||
Default `latest-main` artifacts are **lean** (no ffmpeg). Build and install the media variant:
|
||||
|
||||
```bash
|
||||
# From a clone (heavy; downloads native prebuilds)
|
||||
npm run build:dist:media
|
||||
|
||||
# Install into ~/.bridgeswarm (backs up lean host to bridge-swarm-host.lean.bak)
|
||||
npm run install:capability:media
|
||||
```
|
||||
|
||||
Or download `bridge-swarm-host-media-<platform>-<arch>.zip` from releases and point `BRIDGE_SWARM_MEDIA_URL` at it.
|
||||
|
||||
On macOS the install script extracts addons into `~/.bridgeswarm/tmp` and codesigns `*.bare` / `*.dylib` (same Gatekeeper fix as the lean host). Then **fully quit** the browser and reload the extension.
|
||||
|
||||
Verify:
|
||||
After installing or updating the host on macOS, run `npm run repair:macos` (or `npm run install:capability:media`, which now aliases repair) so new `.bare` addons are extracted and codesigned. Fully quit the browser, then:
|
||||
|
||||
```js
|
||||
await BridgeSwarm.capabilities.has('media') // true
|
||||
@@ -82,25 +64,17 @@ await BridgeSwarm.capabilities.has('media') // true
|
||||
|
||||
Demo: [`examples/media-demo/`](../examples/media-demo/) (`npm run examples` → `/media-demo/`).
|
||||
|
||||
### Local Bare (dev)
|
||||
## Bundled for upcoming packs
|
||||
|
||||
```bash
|
||||
cd native-host
|
||||
npm install bare-media
|
||||
# run entry that registers the pack:
|
||||
node ./node_modules/bare/bin/bare index-media.mjs
|
||||
```
|
||||
These modules are **dependencies of the default host** but not yet exposed as page packs:
|
||||
|
||||
Point the native messaging manifest at that process the same way as the lean host.
|
||||
| Module | Planned pack |
|
||||
|--------|----------------|
|
||||
| `bare-fs` (already used) | `fs` — read/write/list under allowlisted roots |
|
||||
| `bare-sqlite` | `sqlite` — DB under storage |
|
||||
| `bare-fetch` | `net` — CORS-free host fetch |
|
||||
|
||||
## Planned packs (not in this release)
|
||||
|
||||
| Pack | Notes |
|
||||
|------|--------|
|
||||
| **fs / sqlite** | RPC over `bare-fs` / `bare-sqlite` under allowlisted roots |
|
||||
| **net** | Host `fetch`, optional tcp/dgram — CORS-free from the page |
|
||||
|
||||
UI/mobile/build Bare packages (`bare-gtk`, `bare-ios`, `bare-build`, …) are out of scope for BridgeSwarm.
|
||||
UI/mobile/build Bare packages (`bare-gtk`, `bare-ios`, `bare-build`, …) stay out of scope.
|
||||
|
||||
## Host protocol
|
||||
|
||||
@@ -111,4 +85,4 @@ UI/mobile/build Bare packages (`bare-gtk`, `bare-ios`, `bare-build`, …) are ou
|
||||
| `capability` | `{ pack, cmd, payload }` | pack-specific |
|
||||
| `media.<cmd>` | same as `payload` | shortcut when pack installed |
|
||||
|
||||
Unknown pack → `{ ok: false, error: "capability 'media' not installed" }`.
|
||||
Unknown pack → `{ ok: false, error: "capability '…' not installed" }`.
|
||||
|
||||
@@ -0,0 +1,59 @@
|
||||
# Default host modules
|
||||
|
||||
Curated modules shipped in the **default** BridgeSwarm native host. Not every `bare-*` package — only what fits browser + Bare native messaging (swarm, data, local power, media).
|
||||
|
||||
## Always included (direct dependencies)
|
||||
|
||||
### Runtime / platform
|
||||
| Module | Why |
|
||||
|--------|-----|
|
||||
| `bare` | Bare runtime |
|
||||
| `bare-process` | `process` global for packed host |
|
||||
| `bare-module` | Addon / module loading |
|
||||
| `bare-fs` | Storage, cap-jobs, Hyper* on disk |
|
||||
| `bare-path` | Path join/resolve under allowlists |
|
||||
| `bare-stream` | Duplex bridges for NMH / HRPC |
|
||||
|
||||
### Holepunch data + swarm
|
||||
| Module | Why |
|
||||
|--------|-----|
|
||||
| `hyperswarm` | P2P discovery + Noise connections |
|
||||
| `hypercore` / `corestore` | Append-only logs + multi-core store |
|
||||
| `hyperbee` | Key/value |
|
||||
| `hyperdrive` | P2P filesystem |
|
||||
| `autobase` | Multi-writer log |
|
||||
| `hyperdb` / `hyperschema` | Schema DB |
|
||||
| `hrpc` | Typed RPC |
|
||||
| `protomux` / `compact-encoding` / `b4a` | Mux + codecs |
|
||||
|
||||
### Media (default)
|
||||
| Module | Why |
|
||||
|--------|-----|
|
||||
| `bare-media` | High-level image/video API for `BridgeSwarm.media.*` |
|
||||
| `bare-ffmpeg` | Transcode / frame extract (pulled by bare-media; listed explicitly) |
|
||||
| Image codecs | Via bare-media: `bare-jpeg`, `bare-png`, `bare-webp`, `bare-gif`, `bare-heif`, `bare-bmp`, `bare-ico`, `bare-tiff`, `bare-svg`, `bare-image-resample`, `bare-exif` |
|
||||
|
||||
### Local power (bundled for capability packs)
|
||||
| Module | Why |
|
||||
|--------|-----|
|
||||
| `bare-sqlite` | Local SQL under storage (fs/sqlite pack) |
|
||||
| `bare-fetch` | CORS-free HTTPS from the host (net pack; also used by bare-media) |
|
||||
|
||||
## Native addons extracted on install (`--extract-addons`)
|
||||
|
||||
Core: `bare-fs`, `bare-pipe`, `bare-module`, `udx-native`, `sodium-native`, `rocksdb-native`
|
||||
|
||||
Media: `bare-ffmpeg` + image codec addons above
|
||||
|
||||
SQLite: `bare-sqlite` (when present as a native addon)
|
||||
|
||||
## Intentionally not default
|
||||
|
||||
| Area | Examples | Reason |
|
||||
|------|----------|--------|
|
||||
| UI / mobile / build | `bare-gtk`, `bare-ios`, `bare-android`, `bare-build` | Wrong product surface |
|
||||
| Open subprocess | `bare-subprocess` as page API | Too easy to abuse; gate later if needed |
|
||||
| Raw LAN sockets as page API | `bare-tcp` / `bare-dgram` listen | Already transitive for Hyperswarm; no open page API yet |
|
||||
| Everything else in `bare-*` (~150) | — | Size + maintenance; curated packs only |
|
||||
|
||||
See [CAPABILITIES.md](CAPABILITIES.md) for the page-facing packs built on these modules.
|
||||
Reference in New Issue
Block a user