@mastra/platform-workspace 1.0.0 → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +76 -0
- package/dist/address-registry.d.ts +47 -0
- package/dist/address-registry.d.ts.map +1 -0
- package/dist/index.cjs +314 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +312 -3
- package/dist/index.js.map +1 -1
- package/dist/private-net-exec.d.ts +114 -0
- package/dist/private-net-exec.d.ts.map +1 -0
- package/dist/sandbox.d.ts +96 -0
- package/dist/sandbox.d.ts.map +1 -1
- package/package.json +4 -4
package/dist/sandbox.d.ts
CHANGED
|
@@ -3,7 +3,31 @@ import type { CommandResult, ExecuteCommandOptions, InstructionsOption, MastraSa
|
|
|
3
3
|
import { MastraSandbox, ProcessHandle, SandboxProcessManager } from '@mastra/core/workspace';
|
|
4
4
|
import type { PlatformClientOptions } from './client.js';
|
|
5
5
|
import type { DirectExecWebSocketFactory } from './direct-exec.js';
|
|
6
|
+
import type { PrivateNetFetch } from './private-net-exec.js';
|
|
6
7
|
export type PlatformSandboxNetworkIsolation = 'ISOLATED' | 'PRIVATE';
|
|
8
|
+
/**
|
|
9
|
+
* In-process `sandboxId → instanceUrl` map that lets
|
|
10
|
+
* {@link PlatformSandbox.executeCommand} dial the in-sandbox sidecar over
|
|
11
|
+
* Railway's private network instead of paying for a lease + WebSocket
|
|
12
|
+
* round-trip through Railway's public control plane.
|
|
13
|
+
*
|
|
14
|
+
* The workspace proxy discovers each sandbox's IPv6 during
|
|
15
|
+
* `POST /v1/projects/:pid/sandbox` and returns it as `instanceUrl` on the
|
|
16
|
+
* create + get responses (see the platform inline-discovery issue). The
|
|
17
|
+
* `PlatformSandbox` client copies that field into this registry from both
|
|
18
|
+
* {@link PlatformSandbox.start} branches (fresh provision + reattach), evicts
|
|
19
|
+
* on {@link PlatformSandbox.destroy}, and evicts again on any observed
|
|
20
|
+
* transport failure so the next exec falls back to the lease path cleanly.
|
|
21
|
+
*
|
|
22
|
+
* See:
|
|
23
|
+
* - `.scratch/factory-deploy/issue-runtime-sandbox-address-discovery.md`
|
|
24
|
+
* - `.scratch/factory-deploy/issue-platform-sandbox-exec-via-private-network.md`
|
|
25
|
+
*/
|
|
26
|
+
export interface SandboxAddressRegistry {
|
|
27
|
+
set(sandboxId: string, instanceUrl: string): void;
|
|
28
|
+
get(sandboxId: string): string | undefined;
|
|
29
|
+
delete(sandboxId: string): void;
|
|
30
|
+
}
|
|
7
31
|
export interface PlatformSandboxOptions extends Omit<MastraSandboxOptions, 'processes'>, PlatformClientOptions {
|
|
8
32
|
id?: string;
|
|
9
33
|
environmentId?: string;
|
|
@@ -20,6 +44,27 @@ export interface PlatformSandboxOptions extends Omit<MastraSandboxOptions, 'proc
|
|
|
20
44
|
* without a real network socket.
|
|
21
45
|
*/
|
|
22
46
|
webSocketFactory?: DirectExecWebSocketFactory;
|
|
47
|
+
/**
|
|
48
|
+
* Injected fetch implementation used by the private-network exec code path
|
|
49
|
+
* to dial the in-sandbox sidecar. Defaults to `globalThis.fetch` and only
|
|
50
|
+
* exists so tests can drive that transport without a real HTTP server.
|
|
51
|
+
* Note: this is separate from the `fetch` on {@link PlatformClientOptions},
|
|
52
|
+
* which is used for calls to the workspace proxy.
|
|
53
|
+
*/
|
|
54
|
+
privateNetFetch?: PrivateNetFetch;
|
|
55
|
+
/**
|
|
56
|
+
* Registry that maps `sandboxId → instanceUrl` for the private-network
|
|
57
|
+
* exec path. When set, {@link PlatformSandbox.start} populates it from the
|
|
58
|
+
* `instanceUrl` field workspace-proxy returns on create + get responses,
|
|
59
|
+
* and {@link PlatformSandbox.executeCommand} looks it up before every exec
|
|
60
|
+
* and tries the private-network transport first, falling back to the lease
|
|
61
|
+
* path on any transport failure (and invalidating the registry entry so
|
|
62
|
+
* the next call goes to the lease path cleanly). When absent, all execs
|
|
63
|
+
* go straight to the lease path — this is the pre-existing behavior and
|
|
64
|
+
* the expected mode outside the shipyard runtime. See
|
|
65
|
+
* {@link SandboxAddressRegistry}.
|
|
66
|
+
*/
|
|
67
|
+
addressRegistry?: SandboxAddressRegistry;
|
|
23
68
|
}
|
|
24
69
|
/**
|
|
25
70
|
* Diagnostic error thrown when the direct-exec WebSocket transport fails
|
|
@@ -98,6 +143,19 @@ export declare class PlatformSandbox extends MastraSandbox {
|
|
|
98
143
|
private readonly _instructionsOverride?;
|
|
99
144
|
private _createdAt;
|
|
100
145
|
private readonly _webSocketFactory?;
|
|
146
|
+
private readonly _privateNetFetch?;
|
|
147
|
+
/**
|
|
148
|
+
* Registry that maps `sandboxId → instanceUrl` for the private-network
|
|
149
|
+
* exec path. Injected by the composition site via
|
|
150
|
+
* {@link PlatformSandboxOptions.addressRegistry} and populated by this
|
|
151
|
+
* class itself in `start()` when the workspace-proxy's create/reattach
|
|
152
|
+
* response includes an `instanceUrl` field. The registry IS the cache —
|
|
153
|
+
* there is no per-instance mirror on `PlatformSandbox`, so every exec is
|
|
154
|
+
* a `Map.get()` (in the default in-process impl) against the live view.
|
|
155
|
+
* When absent, executes go straight to the lease path with no extra
|
|
156
|
+
* round-trip.
|
|
157
|
+
*/
|
|
158
|
+
private readonly _addressRegistry?;
|
|
101
159
|
/**
|
|
102
160
|
* Cached exec lease for this sandbox. `null` before the first exec and
|
|
103
161
|
* after {@link destroy}. Refreshed when `expiresAt - LEASE_REFRESH_MARGIN_MS < now`
|
|
@@ -128,6 +186,23 @@ export declare class PlatformSandbox extends MastraSandbox {
|
|
|
128
186
|
*/
|
|
129
187
|
clone(options?: SandboxCloneOptions): PlatformSandbox;
|
|
130
188
|
start(): Promise<void>;
|
|
189
|
+
/**
|
|
190
|
+
* Copy `response.instanceUrl` into the injected {@link SandboxAddressRegistry}
|
|
191
|
+
* when both are present. Called from both {@link start} branches (fresh
|
|
192
|
+
* provision + reattach) with the workspace-proxy response for this sandbox.
|
|
193
|
+
*
|
|
194
|
+
* The proxy discovers the IPv6 during `Sandbox.create()` and stores it in
|
|
195
|
+
* `environment_sandboxes.instance_url`; both the create response and
|
|
196
|
+
* `GET /sandbox/:id` echo the same field. The runtime does not do any
|
|
197
|
+
* discovery of its own — it only mirrors the field into an in-process map
|
|
198
|
+
* so {@link executeCommand} can `Map.get()` before every exec without an
|
|
199
|
+
* HTTP round-trip.
|
|
200
|
+
*
|
|
201
|
+
* `null`/absent `instanceUrl` (proxy discovery failed, or an older proxy
|
|
202
|
+
* that predates the field) leaves the registry untouched — executes fall
|
|
203
|
+
* through to the lease path with no branch here.
|
|
204
|
+
*/
|
|
205
|
+
private _populateAddressFromResponse;
|
|
131
206
|
stop(): Promise<void>;
|
|
132
207
|
destroy(): Promise<void>;
|
|
133
208
|
/**
|
|
@@ -170,6 +245,27 @@ export declare class PlatformSandbox extends MastraSandbox {
|
|
|
170
245
|
* returns `{ exitCode: null, timedOut: false }` — that case throws.
|
|
171
246
|
*/
|
|
172
247
|
private _runDirectExec;
|
|
248
|
+
/**
|
|
249
|
+
* Try to run the exec against the in-sandbox sidecar over Railway's private
|
|
250
|
+
* network. Returns the result on success (including non-zero exit codes and
|
|
251
|
+
* timeouts — those are real command results, not failures). Returns
|
|
252
|
+
* `undefined` when the caller should fall back to the lease path:
|
|
253
|
+
*
|
|
254
|
+
* - Transport failure (connection refused, mid-stream drop, no `exit`
|
|
255
|
+
* frame). The registry entry is evicted so subsequent execs skip the
|
|
256
|
+
* private-net dial until the sidecar re-registers.
|
|
257
|
+
* - Sidecar answered with a non-2xx HTTP status. Registry is left intact —
|
|
258
|
+
* the address is still valid; something else is wrong (bad request,
|
|
259
|
+
* sidecar bug). Only this specific exec falls back.
|
|
260
|
+
*/
|
|
261
|
+
private _tryExecViaPrivateNetwork;
|
|
262
|
+
/**
|
|
263
|
+
* Evict this sandbox's entry from the address registry after an observed
|
|
264
|
+
* transport failure. The entry stays gone until the next start() re-reads
|
|
265
|
+
* `instanceUrl` from a workspace-proxy response — until then, execs skip
|
|
266
|
+
* the private-net dial and go straight to the lease path.
|
|
267
|
+
*/
|
|
268
|
+
private _invalidateAddress;
|
|
173
269
|
/**
|
|
174
270
|
* Return a cached exec lease, minting a fresh one when the cache is empty
|
|
175
271
|
* or the JWT is within {@link LEASE_REFRESH_MARGIN_MS} of `expiresAt`.
|
package/dist/sandbox.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EACV,aAAa,EACb,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,WAAW,EACX,cAAc,EACd,mBAAmB,EACnB,WAAW,EACX,mBAAmB,EACpB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,aAAa,EAAE,aAAa,EAAwB,qBAAqB,EAAE,MAAM,wBAAwB,CAAC;AACnH,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,KAAK,EAAE,0BAA0B,EAAa,MAAM,kBAAkB,CAAC;
|
|
1
|
+
{"version":3,"file":"sandbox.d.ts","sourceRoot":"","sources":["../src/sandbox.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@mastra/platform-workspace",
|
|
3
|
-
"version": "1.
|
|
3
|
+
"version": "1.1.0",
|
|
4
4
|
"description": "Mastra Platform workspace sandbox and filesystem providers",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -27,9 +27,9 @@
|
|
|
27
27
|
"tsdown": "0.22.9",
|
|
28
28
|
"typescript": "^6.0.3",
|
|
29
29
|
"vitest": "4.1.10",
|
|
30
|
-
"@internal/
|
|
31
|
-
"@
|
|
32
|
-
"@
|
|
30
|
+
"@internal/types-builder": "0.0.96",
|
|
31
|
+
"@mastra/core": "1.57.0",
|
|
32
|
+
"@internal/lint": "0.0.121"
|
|
33
33
|
},
|
|
34
34
|
"peerDependencies": {
|
|
35
35
|
"@mastra/core": ">=1.4.0-0 <2.0.0-0"
|