Skip to content

Commit 1c92d78

Browse files
NathanFlurryNathanFlurry
authored
Merge pull request #3 from rivet-dev/docs-quickstart-rewrite
docs: rewrite quickstart and add runtimes/system drivers structure
2 parents be38532 + 0f8120c commit 1c92d78

10 files changed

Lines changed: 733 additions & 36 deletions

File tree

‎CLAUDE.md‎

Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -54,6 +54,16 @@ Follow the style in `packages/secure-exec/src/index.ts`.
5454
- comment tricky ordering/invariants; skip noise
5555
- add inline comments and doc comments when behavior is non-obvious, especially where runtime/bridge/driver pieces depend on each other
5656

57+
## Documentation
58+
59+
- docs pages that must stay current with API changes:
60+
- `docs/quickstart.mdx` — update when core setup flow changes
61+
- `docs/api-reference.mdx` — update when any public export signature changes
62+
- `docs/runtimes/node.mdx` — update when NodeRuntime options/behavior changes
63+
- `docs/runtimes/python.mdx` — update when PythonRuntime options/behavior changes
64+
- `docs/system-drivers/node.mdx` — update when createNodeDriver options change
65+
- `docs/system-drivers/browser.mdx` — update when createBrowserDriver options change
66+
5767
## Skills
5868

5969
- create project skills in `.claude/skills/`

‎docs/api-reference.mdx‎

Lines changed: 341 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,341 @@
1+
---
2+
title: API Reference
3+
description: Complete reference for all secure-exec exports.
4+
---
5+
6+
## Runtimes
7+
8+
### `NodeRuntime`
9+
10+
Sandboxed JavaScript runtime using a V8 isolate.
11+
12+
```ts
13+
new NodeRuntime(options: NodeRuntimeOptions)
14+
```
15+
16+
**`NodeRuntimeOptions`**
17+
18+
| Option | Type | Description |
19+
|---|---|---|
20+
| `systemDriver` | `SystemDriver` | Host capabilities (filesystem, network, permissions). **Required.** |
21+
| `runtimeDriverFactory` | `NodeRuntimeDriverFactory` | Creates the isolate execution environment. **Required.** |
22+
| `memoryLimit` | `number` | Isolate memory cap in MB. |
23+
| `cpuTimeLimitMs` | `number` | CPU time budget in ms. |
24+
| `timingMitigation` | `"off" \| "freeze"` | Timing side-channel mitigation. Default `"freeze"`. |
25+
| `onStdio` | `StdioHook` | Default console output hook. |
26+
| `payloadLimits` | `{ base64TransferBytes?: number; jsonPayloadBytes?: number }` | Bridge payload size limits. |
27+
28+
**Methods**
29+
30+
| Method | Returns | Description |
31+
|---|---|---|
32+
| `exec(code, options?)` | `Promise<ExecResult>` | Execute code without a return value. |
33+
| `run<T>(code, filePath?)` | `Promise<RunResult<T>>` | Execute code and return the default export. |
34+
| `network` | `{ fetch, dnsLookup, httpRequest }` | Network access from the host side. |
35+
| `dispose()` | `void` | Release resources synchronously. |
36+
| `terminate()` | `Promise<void>` | Terminate the runtime. |
37+
38+
---
39+
40+
### `PythonRuntime`
41+
42+
Sandboxed Python runtime using Pyodide in a Worker thread.
43+
44+
```ts
45+
new PythonRuntime(options: PythonRuntimeOptions)
46+
```
47+
48+
**`PythonRuntimeOptions`**
49+
50+
| Option | Type | Description |
51+
|---|---|---|
52+
| `systemDriver` | `SystemDriver` | Host capabilities. **Required.** |
53+
| `runtimeDriverFactory` | `PythonRuntimeDriverFactory` | Creates the Pyodide worker. **Required.** |
54+
| `cpuTimeLimitMs` | `number` | CPU time budget in ms. |
55+
| `onStdio` | `StdioHook` | Default console output hook. |
56+
57+
**Methods**
58+
59+
| Method | Returns | Description |
60+
|---|---|---|
61+
| `exec(code, options?)` | `Promise<ExecResult>` | Execute Python code without a return value. |
62+
| `run<T>(code, options?)` | `Promise<PythonRunResult<T>>` | Execute Python code and return a value. |
63+
| `dispose()` | `void` | Release resources synchronously. |
64+
| `terminate()` | `Promise<void>` | Terminate the runtime. |
65+
66+
---
67+
68+
## System Driver Factories
69+
70+
### `createNodeDriver(options?)`
71+
72+
Creates a system driver for Node.js environments.
73+
74+
```ts
75+
createNodeDriver(options?: NodeDriverOptions): SystemDriver
76+
```
77+
78+
**`NodeDriverOptions`**
79+
80+
| Option | Type | Description |
81+
|---|---|---|
82+
| `filesystem` | `VirtualFileSystem` | Custom filesystem. Default: host fs with module overlay. |
83+
| `moduleAccess` | `ModuleAccessOptions` | Node modules overlay config. |
84+
| `networkAdapter` | `NetworkAdapter` | Network implementation. |
85+
| `commandExecutor` | `CommandExecutor` | Child process executor. |
86+
| `permissions` | `Permissions` | Access control rules. Deny-by-default. |
87+
| `useDefaultNetwork` | `boolean` | Enable default Node.js network adapter. |
88+
| `processConfig` | `ProcessConfig` | Process metadata (cwd, env, argv, etc.). |
89+
| `osConfig` | `OSConfig` | OS metadata (platform, arch, homedir, etc.). |
90+
91+
### `createBrowserDriver(options?)`
92+
93+
Creates a system driver for browser environments. Returns a promise because OPFS initialization is async.
94+
95+
```ts
96+
createBrowserDriver(options?: BrowserDriverOptions): Promise<SystemDriver>
97+
```
98+
99+
**`BrowserDriverOptions`**
100+
101+
| Option | Type | Description |
102+
|---|---|---|
103+
| `filesystem` | `"opfs" \| "memory"` | Filesystem backend. Default: `"opfs"`. |
104+
| `permissions` | `Permissions` | Access control rules. Deny-by-default. |
105+
| `useDefaultNetwork` | `boolean` | Enable browser fetch network adapter. |
106+
107+
---
108+
109+
## Runtime Driver Factories
110+
111+
### `createNodeRuntimeDriverFactory(options?)`
112+
113+
Creates a factory for Node.js V8 isolate runtime drivers.
114+
115+
```ts
116+
createNodeRuntimeDriverFactory(options?: {
117+
createIsolate?(memoryLimit: number): unknown;
118+
}): NodeRuntimeDriverFactory
119+
```
120+
121+
### `createBrowserRuntimeDriverFactory(options?)`
122+
123+
Creates a factory for browser Worker-based runtime drivers.
124+
125+
```ts
126+
createBrowserRuntimeDriverFactory(options?: {
127+
workerUrl?: URL | string;
128+
}): NodeRuntimeDriverFactory
129+
```
130+
131+
### `createPyodideRuntimeDriverFactory()`
132+
133+
Creates a factory for Pyodide-based Python runtime drivers.
134+
135+
```ts
136+
createPyodideRuntimeDriverFactory(): PythonRuntimeDriverFactory
137+
```
138+
139+
---
140+
141+
## Filesystem
142+
143+
### `createInMemoryFileSystem()`
144+
145+
Creates a fully in-memory filesystem backed by Maps.
146+
147+
```ts
148+
createInMemoryFileSystem(): InMemoryFileSystem
149+
```
150+
151+
### `createOpfsFileSystem()`
152+
153+
Creates an OPFS-backed filesystem (browser only).
154+
155+
```ts
156+
createOpfsFileSystem(): Promise<VirtualFileSystem>
157+
```
158+
159+
### `NodeFileSystem`
160+
161+
Thin wrapper around Node.js `fs/promises`.
162+
163+
```ts
164+
new NodeFileSystem()
165+
```
166+
167+
### `VirtualFileSystem` interface
168+
169+
| Method | Returns | Description |
170+
|---|---|---|
171+
| `readFile(path)` | `Promise<Uint8Array>` | Read file as bytes. |
172+
| `readTextFile(path)` | `Promise<string>` | Read file as text. |
173+
| `readDir(path)` | `Promise<string[]>` | List directory entries. |
174+
| `readDirWithTypes(path)` | `Promise<DirEntry[]>` | List entries with type info. |
175+
| `writeFile(path, content)` | `Promise<void>` | Write file. |
176+
| `createDir(path)` | `Promise<void>` | Create directory. |
177+
| `mkdir(path)` | `Promise<void>` | Create directory (alias). |
178+
| `exists(path)` | `Promise<boolean>` | Check if path exists. |
179+
| `stat(path)` | `Promise<StatInfo>` | Get file metadata. |
180+
| `removeFile(path)` | `Promise<void>` | Delete a file. |
181+
| `removeDir(path)` | `Promise<void>` | Delete a directory. |
182+
| `rename(old, new)` | `Promise<void>` | Rename a file or directory. |
183+
184+
---
185+
186+
## Network
187+
188+
### `createDefaultNetworkAdapter()`
189+
190+
Creates a network adapter with real fetch, DNS, and HTTP support (Node.js only).
191+
192+
```ts
193+
createDefaultNetworkAdapter(): NetworkAdapter
194+
```
195+
196+
### `createBrowserNetworkAdapter()`
197+
198+
Creates a fetch-only network adapter for browser environments. No DNS support.
199+
200+
```ts
201+
createBrowserNetworkAdapter(): NetworkAdapter
202+
```
203+
204+
### `NetworkAdapter` interface
205+
206+
| Method | Returns | Description |
207+
|---|---|---|
208+
| `fetch(url, options?)` | `Promise<FetchResponse>` | HTTP fetch. |
209+
| `dnsLookup(hostname)` | `Promise<DnsResult>` | DNS resolution. |
210+
| `httpRequest(url, options?)` | `Promise<HttpResponse>` | Low-level HTTP request. |
211+
| `httpServerListen?(options)` | `Promise<{ address }>` | Start a loopback HTTP server. |
212+
| `httpServerClose?(serverId)` | `Promise<void>` | Close a loopback HTTP server. |
213+
214+
---
215+
216+
## Permissions
217+
218+
### Pre-built helpers
219+
220+
| Export | Description |
221+
|---|---|
222+
| `allowAll` | Allow all operations. |
223+
| `allowAllFs` | Allow all filesystem operations. |
224+
| `allowAllNetwork` | Allow all network operations. |
225+
| `allowAllChildProcess` | Allow all child process spawning. |
226+
| `allowAllEnv` | Allow all environment variable access. |
227+
228+
### `Permissions` type
229+
230+
```ts
231+
type Permissions = {
232+
fs?: PermissionCheck<FsAccessRequest>;
233+
network?: PermissionCheck<NetworkAccessRequest>;
234+
childProcess?: PermissionCheck<ChildProcessAccessRequest>;
235+
env?: PermissionCheck<EnvAccessRequest>;
236+
};
237+
```
238+
239+
Each field accepts a `PermissionCheck`, which is either a boolean or a function `(request) => boolean | Promise<boolean>`.
240+
241+
---
242+
243+
## Execution Types
244+
245+
### `ExecOptions`
246+
247+
| Option | Type | Description |
248+
|---|---|---|
249+
| `filePath` | `string` | Script filename for error messages. |
250+
| `env` | `Record<string, string>` | Override environment variables. |
251+
| `cwd` | `string` | Working directory. |
252+
| `stdin` | `string` | Stdin data. |
253+
| `cpuTimeLimitMs` | `number` | CPU budget override. |
254+
| `timingMitigation` | `"off" \| "freeze"` | Timing mitigation override. |
255+
| `onStdio` | `StdioHook` | Per-execution stdio hook. |
256+
257+
### `ExecResult`
258+
259+
```ts
260+
{ code: number; errorMessage?: string }
261+
```
262+
263+
### `RunResult<T>`
264+
265+
```ts
266+
{ code: number; errorMessage?: string; exports?: T }
267+
```
268+
269+
### `PythonRunResult<T>`
270+
271+
```ts
272+
{ code: number; errorMessage?: string; value?: T; globals?: Record<string, unknown> }
273+
```
274+
275+
### `PythonRunOptions`
276+
277+
Extends `ExecOptions` with:
278+
279+
| Option | Type | Description |
280+
|---|---|---|
281+
| `globals` | `string[]` | Python globals to return. |
282+
283+
### `StdioHook`
284+
285+
```ts
286+
type StdioHook = (event: { channel: "stdout" | "stderr"; message: string }) => void;
287+
```
288+
289+
---
290+
291+
## Configuration Types
292+
293+
### `ProcessConfig`
294+
295+
| Field | Type | Default |
296+
|---|---|---|
297+
| `platform` | `string` | — |
298+
| `arch` | `string` | — |
299+
| `version` | `string` | — |
300+
| `cwd` | `string` | `"/root"` |
301+
| `env` | `Record<string, string>` | — |
302+
| `argv` | `string[]` | — |
303+
| `execPath` | `string` | — |
304+
| `pid` | `number` | — |
305+
| `ppid` | `number` | — |
306+
| `uid` | `number` | — |
307+
| `gid` | `number` | — |
308+
| `stdin` | `string` | — |
309+
| `timingMitigation` | `"off" \| "freeze"` | — |
310+
| `frozenTimeMs` | `number` | — |
311+
312+
### `OSConfig`
313+
314+
| Field | Type | Default |
315+
|---|---|---|
316+
| `platform` | `string` | — |
317+
| `arch` | `string` | — |
318+
| `type` | `string` | — |
319+
| `release` | `string` | — |
320+
| `version` | `string` | — |
321+
| `homedir` | `string` | `"/root"` |
322+
| `tmpdir` | `string` | `"/tmp"` |
323+
| `hostname` | `string` | — |
324+
325+
### `SystemDriver`
326+
327+
```ts
328+
type SystemDriver = {
329+
filesystem?: VirtualFileSystem;
330+
network?: NetworkAdapter;
331+
commandExecutor?: CommandExecutor;
332+
permissions?: Permissions;
333+
runtime: DriverRuntimeConfig;
334+
};
335+
```
336+
337+
### `CommandExecutor` interface
338+
339+
| Method | Returns | Description |
340+
|---|---|---|
341+
| `spawn(command, args, options?)` | `SpawnedProcess` | Spawn a child process. |

‎docs/docs.json‎

Lines changed: 17 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,23 @@
1111
"groups": [
1212
{
1313
"group": "Getting Started",
14-
"pages": ["quickstart"]
14+
"pages": ["quickstart", "api-reference"]
15+
},
16+
{
17+
"group": "Runtimes",
18+
"pages": [
19+
"runtimes/overview",
20+
"runtimes/node",
21+
"runtimes/python"
22+
]
23+
},
24+
{
25+
"group": "System Drivers",
26+
"pages": [
27+
"system-drivers/overview",
28+
"system-drivers/node",
29+
"system-drivers/browser"
30+
]
1531
},
1632
{
1733
"group": "Security",

0 commit comments

Comments
 (0)