@cloudflare/sandbox 0.4.14 → 0.4.16
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/.turbo/turbo-build.log +7 -7
- package/CHANGELOG.md +20 -0
- package/Dockerfile +70 -29
- package/README.md +9 -1
- package/dist/index.d.ts +386 -322
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +136 -2
- package/dist/index.js.map +1 -1
- package/package.json +1 -1
- package/src/clients/git-client.ts +7 -0
- package/src/clients/index.ts +4 -0
- package/src/clients/utility-client.ts +33 -0
- package/src/index.ts +6 -2
- package/src/sandbox.ts +37 -4
- package/src/version.ts +1 -1
- package/tests/git-client.test.ts +72 -0
- package/tests/sandbox.test.ts +33 -0
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,292 @@
|
|
|
1
1
|
import { Container } from "@cloudflare/containers";
|
|
2
2
|
|
|
3
|
+
//#region ../shared/dist/logger/types.d.ts
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* Logger types for Cloudflare Sandbox SDK
|
|
7
|
+
*
|
|
8
|
+
* Provides structured, trace-aware logging across Worker, Durable Object, and Container.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Log levels (from most to least verbose)
|
|
12
|
+
*/
|
|
13
|
+
declare enum LogLevel {
|
|
14
|
+
DEBUG = 0,
|
|
15
|
+
INFO = 1,
|
|
16
|
+
WARN = 2,
|
|
17
|
+
ERROR = 3,
|
|
18
|
+
}
|
|
19
|
+
type LogComponent = 'container' | 'sandbox-do' | 'executor';
|
|
20
|
+
/**
|
|
21
|
+
* Context metadata included in every log entry
|
|
22
|
+
*/
|
|
23
|
+
interface LogContext {
|
|
24
|
+
/**
|
|
25
|
+
* Unique trace ID for request correlation across distributed components
|
|
26
|
+
* Format: "tr_" + 16 hex chars (e.g., "tr_7f3a9b2c4e5d6f1a")
|
|
27
|
+
*/
|
|
28
|
+
traceId: string;
|
|
29
|
+
/**
|
|
30
|
+
* Component that generated the log
|
|
31
|
+
*/
|
|
32
|
+
component: LogComponent;
|
|
33
|
+
/**
|
|
34
|
+
* Sandbox identifier (which sandbox instance)
|
|
35
|
+
*/
|
|
36
|
+
sandboxId?: string;
|
|
37
|
+
/**
|
|
38
|
+
* Session identifier (which session within sandbox)
|
|
39
|
+
*/
|
|
40
|
+
sessionId?: string;
|
|
41
|
+
/**
|
|
42
|
+
* Process identifier (which background process)
|
|
43
|
+
*/
|
|
44
|
+
processId?: string;
|
|
45
|
+
/**
|
|
46
|
+
* Command identifier (which command execution)
|
|
47
|
+
*/
|
|
48
|
+
commandId?: string;
|
|
49
|
+
/**
|
|
50
|
+
* Operation name (e.g., 'exec', 'startProcess', 'writeFile')
|
|
51
|
+
*/
|
|
52
|
+
operation?: string;
|
|
53
|
+
/**
|
|
54
|
+
* Duration in milliseconds
|
|
55
|
+
*/
|
|
56
|
+
duration?: number;
|
|
57
|
+
/**
|
|
58
|
+
* Extensible for additional metadata
|
|
59
|
+
*/
|
|
60
|
+
[key: string]: unknown;
|
|
61
|
+
}
|
|
62
|
+
/**
|
|
63
|
+
* Logger interface for structured logging
|
|
64
|
+
*
|
|
65
|
+
* All methods accept optional context that gets merged with the logger's base context.
|
|
66
|
+
*/
|
|
67
|
+
interface Logger {
|
|
68
|
+
/**
|
|
69
|
+
* Log debug-level message (most verbose, typically disabled in production)
|
|
70
|
+
*
|
|
71
|
+
* @param message Human-readable message
|
|
72
|
+
* @param context Optional additional context
|
|
73
|
+
*/
|
|
74
|
+
debug(message: string, context?: Partial<LogContext>): void;
|
|
75
|
+
/**
|
|
76
|
+
* Log info-level message (normal operational events)
|
|
77
|
+
*
|
|
78
|
+
* @param message Human-readable message
|
|
79
|
+
* @param context Optional additional context
|
|
80
|
+
*/
|
|
81
|
+
info(message: string, context?: Partial<LogContext>): void;
|
|
82
|
+
/**
|
|
83
|
+
* Log warning-level message (recoverable issues, degraded state)
|
|
84
|
+
*
|
|
85
|
+
* @param message Human-readable message
|
|
86
|
+
* @param context Optional additional context
|
|
87
|
+
*/
|
|
88
|
+
warn(message: string, context?: Partial<LogContext>): void;
|
|
89
|
+
/**
|
|
90
|
+
* Log error-level message (failures, exceptions)
|
|
91
|
+
*
|
|
92
|
+
* @param message Human-readable message
|
|
93
|
+
* @param error Optional Error object to include
|
|
94
|
+
* @param context Optional additional context
|
|
95
|
+
*/
|
|
96
|
+
error(message: string, error?: Error, context?: Partial<LogContext>): void;
|
|
97
|
+
/**
|
|
98
|
+
* Create a child logger with additional context
|
|
99
|
+
*
|
|
100
|
+
* The child logger inherits all context from the parent and adds new context.
|
|
101
|
+
* This is useful for adding operation-specific context without passing through parameters.
|
|
102
|
+
*
|
|
103
|
+
* @param context Additional context to merge
|
|
104
|
+
* @returns New logger instance with merged context
|
|
105
|
+
*
|
|
106
|
+
* @example
|
|
107
|
+
* const logger = createLogger({ component: 'sandbox-do', traceId: 'tr_abc123' });
|
|
108
|
+
* const execLogger = logger.child({ operation: 'exec', commandId: 'cmd-456' });
|
|
109
|
+
* execLogger.info('Command started'); // Includes all context: component, traceId, operation, commandId
|
|
110
|
+
*/
|
|
111
|
+
child(context: Partial<LogContext>): Logger;
|
|
112
|
+
}
|
|
113
|
+
//#endregion
|
|
114
|
+
//#region ../shared/dist/logger/trace-context.d.ts
|
|
115
|
+
/**
|
|
116
|
+
* Trace context utilities for request correlation
|
|
117
|
+
*
|
|
118
|
+
* Trace IDs enable correlating logs across distributed components:
|
|
119
|
+
* Worker → Durable Object → Container → back
|
|
120
|
+
*
|
|
121
|
+
* The trace ID is propagated via the X-Trace-Id HTTP header.
|
|
122
|
+
*/
|
|
123
|
+
/**
|
|
124
|
+
* Utility for managing trace context across distributed components
|
|
125
|
+
*/
|
|
126
|
+
declare class TraceContext {
|
|
127
|
+
/**
|
|
128
|
+
* HTTP header name for trace ID propagation
|
|
129
|
+
*/
|
|
130
|
+
private static readonly TRACE_HEADER;
|
|
131
|
+
/**
|
|
132
|
+
* Generate a new trace ID
|
|
133
|
+
*
|
|
134
|
+
* Format: "tr_" + 16 random hex characters
|
|
135
|
+
* Example: "tr_7f3a9b2c4e5d6f1a"
|
|
136
|
+
*
|
|
137
|
+
* @returns Newly generated trace ID
|
|
138
|
+
*/
|
|
139
|
+
static generate(): string;
|
|
140
|
+
/**
|
|
141
|
+
* Extract trace ID from HTTP request headers
|
|
142
|
+
*
|
|
143
|
+
* @param headers Request headers
|
|
144
|
+
* @returns Trace ID if present, null otherwise
|
|
145
|
+
*/
|
|
146
|
+
static fromHeaders(headers: Headers): string | null;
|
|
147
|
+
/**
|
|
148
|
+
* Create headers object with trace ID for outgoing requests
|
|
149
|
+
*
|
|
150
|
+
* @param traceId Trace ID to include
|
|
151
|
+
* @returns Headers object with X-Trace-Id set
|
|
152
|
+
*/
|
|
153
|
+
static toHeaders(traceId: string): Record<string, string>;
|
|
154
|
+
/**
|
|
155
|
+
* Get the header name used for trace ID propagation
|
|
156
|
+
*
|
|
157
|
+
* @returns Header name ("X-Trace-Id")
|
|
158
|
+
*/
|
|
159
|
+
static getHeaderName(): string;
|
|
160
|
+
}
|
|
161
|
+
//#endregion
|
|
162
|
+
//#region ../shared/dist/logger/index.d.ts
|
|
163
|
+
|
|
164
|
+
/**
|
|
165
|
+
* Create a no-op logger for testing
|
|
166
|
+
*
|
|
167
|
+
* Returns a logger that implements the Logger interface but does nothing.
|
|
168
|
+
* Useful for tests that don't need actual logging output.
|
|
169
|
+
*
|
|
170
|
+
* @returns No-op logger instance
|
|
171
|
+
*
|
|
172
|
+
* @example
|
|
173
|
+
* ```typescript
|
|
174
|
+
* // In tests
|
|
175
|
+
* const client = new HttpClient({
|
|
176
|
+
* baseUrl: 'http://test.com',
|
|
177
|
+
* logger: createNoOpLogger() // Optional - tests can enable real logging if needed
|
|
178
|
+
* });
|
|
179
|
+
* ```
|
|
180
|
+
*/
|
|
181
|
+
declare function createNoOpLogger(): Logger;
|
|
182
|
+
/**
|
|
183
|
+
* Get the current logger from AsyncLocalStorage
|
|
184
|
+
*
|
|
185
|
+
* @throws Error if no logger is initialized in the current async context
|
|
186
|
+
* @returns Current logger instance
|
|
187
|
+
*
|
|
188
|
+
* @example
|
|
189
|
+
* ```typescript
|
|
190
|
+
* function someHelperFunction() {
|
|
191
|
+
* const logger = getLogger(); // Automatically has all context!
|
|
192
|
+
* logger.info('Helper called');
|
|
193
|
+
* }
|
|
194
|
+
* ```
|
|
195
|
+
*/
|
|
196
|
+
declare function getLogger(): Logger;
|
|
197
|
+
/**
|
|
198
|
+
* Run a function with a logger stored in AsyncLocalStorage
|
|
199
|
+
*
|
|
200
|
+
* The logger is available to all code within the function via getLogger().
|
|
201
|
+
* This is typically called at request entry points (fetch handler) and when
|
|
202
|
+
* creating child loggers with additional context.
|
|
203
|
+
*
|
|
204
|
+
* @param logger Logger instance to store in context
|
|
205
|
+
* @param fn Function to execute with logger context
|
|
206
|
+
* @returns Result of the function
|
|
207
|
+
*
|
|
208
|
+
* @example
|
|
209
|
+
* ```typescript
|
|
210
|
+
* // At request entry point
|
|
211
|
+
* async fetch(request: Request): Promise<Response> {
|
|
212
|
+
* const logger = createLogger({ component: 'sandbox-do', traceId: 'tr_abc' });
|
|
213
|
+
* return runWithLogger(logger, async () => {
|
|
214
|
+
* return await this.handleRequest(request);
|
|
215
|
+
* });
|
|
216
|
+
* }
|
|
217
|
+
*
|
|
218
|
+
* // When adding operation context
|
|
219
|
+
* async exec(command: string) {
|
|
220
|
+
* const logger = getLogger().child({ operation: 'exec', commandId: 'cmd-123' });
|
|
221
|
+
* return runWithLogger(logger, async () => {
|
|
222
|
+
* logger.info('Command started');
|
|
223
|
+
* await this.executeCommand(command); // Nested calls get the child logger
|
|
224
|
+
* logger.info('Command completed');
|
|
225
|
+
* });
|
|
226
|
+
* }
|
|
227
|
+
* ```
|
|
228
|
+
*/
|
|
229
|
+
declare function runWithLogger<T>(logger: Logger, fn: () => T | Promise<T>): T | Promise<T>;
|
|
230
|
+
/**
|
|
231
|
+
* Create a new logger instance
|
|
232
|
+
*
|
|
233
|
+
* @param context Base context for the logger. Must include 'component'.
|
|
234
|
+
* TraceId will be auto-generated if not provided.
|
|
235
|
+
* @returns New logger instance
|
|
236
|
+
*
|
|
237
|
+
* @example
|
|
238
|
+
* ```typescript
|
|
239
|
+
* // In Durable Object
|
|
240
|
+
* const logger = createLogger({
|
|
241
|
+
* component: 'sandbox-do',
|
|
242
|
+
* traceId: TraceContext.fromHeaders(request.headers) || TraceContext.generate(),
|
|
243
|
+
* sandboxId: this.id
|
|
244
|
+
* });
|
|
245
|
+
*
|
|
246
|
+
* // In Container
|
|
247
|
+
* const logger = createLogger({
|
|
248
|
+
* component: 'container',
|
|
249
|
+
* traceId: TraceContext.fromHeaders(request.headers)!,
|
|
250
|
+
* sessionId: this.id
|
|
251
|
+
* });
|
|
252
|
+
* ```
|
|
253
|
+
*/
|
|
254
|
+
declare function createLogger(context: Partial<LogContext> & {
|
|
255
|
+
component: LogComponent;
|
|
256
|
+
}): Logger;
|
|
257
|
+
//#endregion
|
|
258
|
+
//#region ../shared/dist/git.d.ts
|
|
259
|
+
/**
|
|
260
|
+
* Redact credentials from URLs for secure logging
|
|
261
|
+
*
|
|
262
|
+
* Replaces any credentials (username:password, tokens, etc.) embedded
|
|
263
|
+
* in URLs with ****** to prevent sensitive data exposure in logs.
|
|
264
|
+
* Works with URLs embedded in text (e.g., "Error: https://token@github.com/repo.git failed")
|
|
265
|
+
*
|
|
266
|
+
* @param text - String that may contain URLs with credentials
|
|
267
|
+
* @returns String with credentials redacted from any URLs
|
|
268
|
+
*/
|
|
269
|
+
declare function redactCredentials(text: string): string;
|
|
270
|
+
/**
|
|
271
|
+
* Sanitize data by redacting credentials from any strings
|
|
272
|
+
* Recursively processes objects and arrays to ensure credentials are never leaked
|
|
273
|
+
*/
|
|
274
|
+
declare function sanitizeGitData<T>(data: T): T;
|
|
275
|
+
/**
|
|
276
|
+
* Logger wrapper that automatically sanitizes git credentials
|
|
277
|
+
*/
|
|
278
|
+
declare class GitLogger implements Logger {
|
|
279
|
+
private readonly baseLogger;
|
|
280
|
+
constructor(baseLogger: Logger);
|
|
281
|
+
private sanitizeContext;
|
|
282
|
+
private sanitizeError;
|
|
283
|
+
debug(message: string, context?: Partial<LogContext>): void;
|
|
284
|
+
info(message: string, context?: Partial<LogContext>): void;
|
|
285
|
+
warn(message: string, context?: Partial<LogContext>): void;
|
|
286
|
+
error(message: string, error?: Error, context?: Partial<LogContext>): void;
|
|
287
|
+
child(context: Partial<LogContext>): Logger;
|
|
288
|
+
}
|
|
289
|
+
//#endregion
|
|
3
290
|
//#region ../shared/dist/interpreter-types.d.ts
|
|
4
291
|
interface CreateContextOptions {
|
|
5
292
|
/**
|
|
@@ -168,349 +455,96 @@ interface ChartData {
|
|
|
168
455
|
/**
|
|
169
456
|
* Library that generated the chart
|
|
170
457
|
*/
|
|
171
|
-
library?: 'matplotlib' | 'plotly' | 'altair' | 'seaborn' | 'unknown';
|
|
172
|
-
/**
|
|
173
|
-
* Base64 encoded image if available
|
|
174
|
-
*/
|
|
175
|
-
image?: string;
|
|
176
|
-
}
|
|
177
|
-
interface ExecutionError {
|
|
178
|
-
/**
|
|
179
|
-
* Error name/type (e.g., 'NameError', 'SyntaxError')
|
|
180
|
-
*/
|
|
181
|
-
name: string;
|
|
182
|
-
/**
|
|
183
|
-
* Error message
|
|
184
|
-
*/
|
|
185
|
-
message: string;
|
|
186
|
-
/**
|
|
187
|
-
* Stack trace
|
|
188
|
-
*/
|
|
189
|
-
traceback: string[];
|
|
190
|
-
/**
|
|
191
|
-
* Line number where error occurred
|
|
192
|
-
*/
|
|
193
|
-
lineNumber?: number;
|
|
194
|
-
}
|
|
195
|
-
interface ExecutionResult {
|
|
196
|
-
code: string;
|
|
197
|
-
logs: {
|
|
198
|
-
stdout: string[];
|
|
199
|
-
stderr: string[];
|
|
200
|
-
};
|
|
201
|
-
error?: ExecutionError;
|
|
202
|
-
executionCount?: number;
|
|
203
|
-
results: Array<{
|
|
204
|
-
text?: string;
|
|
205
|
-
html?: string;
|
|
206
|
-
png?: string;
|
|
207
|
-
jpeg?: string;
|
|
208
|
-
svg?: string;
|
|
209
|
-
latex?: string;
|
|
210
|
-
markdown?: string;
|
|
211
|
-
javascript?: string;
|
|
212
|
-
json?: any;
|
|
213
|
-
chart?: ChartData;
|
|
214
|
-
data?: any;
|
|
215
|
-
}>;
|
|
216
|
-
}
|
|
217
|
-
declare class Execution {
|
|
218
|
-
readonly code: string;
|
|
219
|
-
readonly context: CodeContext;
|
|
220
|
-
/**
|
|
221
|
-
* All results from the execution
|
|
222
|
-
*/
|
|
223
|
-
results: Result[];
|
|
224
|
-
/**
|
|
225
|
-
* Accumulated stdout and stderr
|
|
226
|
-
*/
|
|
227
|
-
logs: {
|
|
228
|
-
stdout: string[];
|
|
229
|
-
stderr: string[];
|
|
230
|
-
};
|
|
231
|
-
/**
|
|
232
|
-
* Execution error if any
|
|
233
|
-
*/
|
|
234
|
-
error?: ExecutionError;
|
|
235
|
-
/**
|
|
236
|
-
* Execution count (for interpreter)
|
|
237
|
-
*/
|
|
238
|
-
executionCount?: number;
|
|
239
|
-
constructor(code: string, context: CodeContext);
|
|
240
|
-
/**
|
|
241
|
-
* Convert to a plain object for serialization
|
|
242
|
-
*/
|
|
243
|
-
toJSON(): ExecutionResult;
|
|
244
|
-
}
|
|
245
|
-
declare class ResultImpl implements Result {
|
|
246
|
-
private raw;
|
|
247
|
-
constructor(raw: any);
|
|
248
|
-
get text(): string | undefined;
|
|
249
|
-
get html(): string | undefined;
|
|
250
|
-
get png(): string | undefined;
|
|
251
|
-
get jpeg(): string | undefined;
|
|
252
|
-
get svg(): string | undefined;
|
|
253
|
-
get latex(): string | undefined;
|
|
254
|
-
get markdown(): string | undefined;
|
|
255
|
-
get javascript(): string | undefined;
|
|
256
|
-
get json(): any;
|
|
257
|
-
get chart(): ChartData | undefined;
|
|
258
|
-
get data(): any;
|
|
259
|
-
formats(): string[];
|
|
260
|
-
}
|
|
261
|
-
//#endregion
|
|
262
|
-
//#region ../shared/dist/logger/types.d.ts
|
|
263
|
-
/**
|
|
264
|
-
* Logger types for Cloudflare Sandbox SDK
|
|
265
|
-
*
|
|
266
|
-
* Provides structured, trace-aware logging across Worker, Durable Object, and Container.
|
|
267
|
-
*/
|
|
268
|
-
/**
|
|
269
|
-
* Log levels (from most to least verbose)
|
|
270
|
-
*/
|
|
271
|
-
declare enum LogLevel {
|
|
272
|
-
DEBUG = 0,
|
|
273
|
-
INFO = 1,
|
|
274
|
-
WARN = 2,
|
|
275
|
-
ERROR = 3,
|
|
276
|
-
}
|
|
277
|
-
type LogComponent = 'container' | 'sandbox-do' | 'executor';
|
|
278
|
-
/**
|
|
279
|
-
* Context metadata included in every log entry
|
|
280
|
-
*/
|
|
281
|
-
interface LogContext {
|
|
282
|
-
/**
|
|
283
|
-
* Unique trace ID for request correlation across distributed components
|
|
284
|
-
* Format: "tr_" + 16 hex chars (e.g., "tr_7f3a9b2c4e5d6f1a")
|
|
285
|
-
*/
|
|
286
|
-
traceId: string;
|
|
287
|
-
/**
|
|
288
|
-
* Component that generated the log
|
|
289
|
-
*/
|
|
290
|
-
component: LogComponent;
|
|
291
|
-
/**
|
|
292
|
-
* Sandbox identifier (which sandbox instance)
|
|
293
|
-
*/
|
|
294
|
-
sandboxId?: string;
|
|
295
|
-
/**
|
|
296
|
-
* Session identifier (which session within sandbox)
|
|
297
|
-
*/
|
|
298
|
-
sessionId?: string;
|
|
299
|
-
/**
|
|
300
|
-
* Process identifier (which background process)
|
|
301
|
-
*/
|
|
302
|
-
processId?: string;
|
|
303
|
-
/**
|
|
304
|
-
* Command identifier (which command execution)
|
|
305
|
-
*/
|
|
306
|
-
commandId?: string;
|
|
307
|
-
/**
|
|
308
|
-
* Operation name (e.g., 'exec', 'startProcess', 'writeFile')
|
|
309
|
-
*/
|
|
310
|
-
operation?: string;
|
|
311
|
-
/**
|
|
312
|
-
* Duration in milliseconds
|
|
313
|
-
*/
|
|
314
|
-
duration?: number;
|
|
315
|
-
/**
|
|
316
|
-
* Extensible for additional metadata
|
|
317
|
-
*/
|
|
318
|
-
[key: string]: unknown;
|
|
319
|
-
}
|
|
320
|
-
/**
|
|
321
|
-
* Logger interface for structured logging
|
|
322
|
-
*
|
|
323
|
-
* All methods accept optional context that gets merged with the logger's base context.
|
|
324
|
-
*/
|
|
325
|
-
interface Logger {
|
|
458
|
+
library?: 'matplotlib' | 'plotly' | 'altair' | 'seaborn' | 'unknown';
|
|
326
459
|
/**
|
|
327
|
-
*
|
|
328
|
-
*
|
|
329
|
-
* @param message Human-readable message
|
|
330
|
-
* @param context Optional additional context
|
|
460
|
+
* Base64 encoded image if available
|
|
331
461
|
*/
|
|
332
|
-
|
|
462
|
+
image?: string;
|
|
463
|
+
}
|
|
464
|
+
interface ExecutionError {
|
|
333
465
|
/**
|
|
334
|
-
*
|
|
335
|
-
*
|
|
336
|
-
* @param message Human-readable message
|
|
337
|
-
* @param context Optional additional context
|
|
466
|
+
* Error name/type (e.g., 'NameError', 'SyntaxError')
|
|
338
467
|
*/
|
|
339
|
-
|
|
468
|
+
name: string;
|
|
340
469
|
/**
|
|
341
|
-
*
|
|
342
|
-
*
|
|
343
|
-
* @param message Human-readable message
|
|
344
|
-
* @param context Optional additional context
|
|
470
|
+
* Error message
|
|
345
471
|
*/
|
|
346
|
-
|
|
472
|
+
message: string;
|
|
347
473
|
/**
|
|
348
|
-
*
|
|
349
|
-
*
|
|
350
|
-
* @param message Human-readable message
|
|
351
|
-
* @param error Optional Error object to include
|
|
352
|
-
* @param context Optional additional context
|
|
474
|
+
* Stack trace
|
|
353
475
|
*/
|
|
354
|
-
|
|
476
|
+
traceback: string[];
|
|
355
477
|
/**
|
|
356
|
-
*
|
|
357
|
-
*
|
|
358
|
-
* The child logger inherits all context from the parent and adds new context.
|
|
359
|
-
* This is useful for adding operation-specific context without passing through parameters.
|
|
360
|
-
*
|
|
361
|
-
* @param context Additional context to merge
|
|
362
|
-
* @returns New logger instance with merged context
|
|
363
|
-
*
|
|
364
|
-
* @example
|
|
365
|
-
* const logger = createLogger({ component: 'sandbox-do', traceId: 'tr_abc123' });
|
|
366
|
-
* const execLogger = logger.child({ operation: 'exec', commandId: 'cmd-456' });
|
|
367
|
-
* execLogger.info('Command started'); // Includes all context: component, traceId, operation, commandId
|
|
478
|
+
* Line number where error occurred
|
|
368
479
|
*/
|
|
369
|
-
|
|
480
|
+
lineNumber?: number;
|
|
370
481
|
}
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
|
|
383
|
-
|
|
384
|
-
|
|
482
|
+
interface ExecutionResult {
|
|
483
|
+
code: string;
|
|
484
|
+
logs: {
|
|
485
|
+
stdout: string[];
|
|
486
|
+
stderr: string[];
|
|
487
|
+
};
|
|
488
|
+
error?: ExecutionError;
|
|
489
|
+
executionCount?: number;
|
|
490
|
+
results: Array<{
|
|
491
|
+
text?: string;
|
|
492
|
+
html?: string;
|
|
493
|
+
png?: string;
|
|
494
|
+
jpeg?: string;
|
|
495
|
+
svg?: string;
|
|
496
|
+
latex?: string;
|
|
497
|
+
markdown?: string;
|
|
498
|
+
javascript?: string;
|
|
499
|
+
json?: any;
|
|
500
|
+
chart?: ChartData;
|
|
501
|
+
data?: any;
|
|
502
|
+
}>;
|
|
503
|
+
}
|
|
504
|
+
declare class Execution {
|
|
505
|
+
readonly code: string;
|
|
506
|
+
readonly context: CodeContext;
|
|
385
507
|
/**
|
|
386
|
-
*
|
|
508
|
+
* All results from the execution
|
|
387
509
|
*/
|
|
388
|
-
|
|
510
|
+
results: Result[];
|
|
389
511
|
/**
|
|
390
|
-
*
|
|
391
|
-
*
|
|
392
|
-
* Format: "tr_" + 16 random hex characters
|
|
393
|
-
* Example: "tr_7f3a9b2c4e5d6f1a"
|
|
394
|
-
*
|
|
395
|
-
* @returns Newly generated trace ID
|
|
512
|
+
* Accumulated stdout and stderr
|
|
396
513
|
*/
|
|
397
|
-
|
|
514
|
+
logs: {
|
|
515
|
+
stdout: string[];
|
|
516
|
+
stderr: string[];
|
|
517
|
+
};
|
|
398
518
|
/**
|
|
399
|
-
*
|
|
400
|
-
*
|
|
401
|
-
* @param headers Request headers
|
|
402
|
-
* @returns Trace ID if present, null otherwise
|
|
519
|
+
* Execution error if any
|
|
403
520
|
*/
|
|
404
|
-
|
|
521
|
+
error?: ExecutionError;
|
|
405
522
|
/**
|
|
406
|
-
*
|
|
407
|
-
*
|
|
408
|
-
* @param traceId Trace ID to include
|
|
409
|
-
* @returns Headers object with X-Trace-Id set
|
|
523
|
+
* Execution count (for interpreter)
|
|
410
524
|
*/
|
|
411
|
-
|
|
525
|
+
executionCount?: number;
|
|
526
|
+
constructor(code: string, context: CodeContext);
|
|
412
527
|
/**
|
|
413
|
-
*
|
|
414
|
-
*
|
|
415
|
-
* @returns Header name ("X-Trace-Id")
|
|
528
|
+
* Convert to a plain object for serialization
|
|
416
529
|
*/
|
|
417
|
-
|
|
530
|
+
toJSON(): ExecutionResult;
|
|
531
|
+
}
|
|
532
|
+
declare class ResultImpl implements Result {
|
|
533
|
+
private raw;
|
|
534
|
+
constructor(raw: any);
|
|
535
|
+
get text(): string | undefined;
|
|
536
|
+
get html(): string | undefined;
|
|
537
|
+
get png(): string | undefined;
|
|
538
|
+
get jpeg(): string | undefined;
|
|
539
|
+
get svg(): string | undefined;
|
|
540
|
+
get latex(): string | undefined;
|
|
541
|
+
get markdown(): string | undefined;
|
|
542
|
+
get javascript(): string | undefined;
|
|
543
|
+
get json(): any;
|
|
544
|
+
get chart(): ChartData | undefined;
|
|
545
|
+
get data(): any;
|
|
546
|
+
formats(): string[];
|
|
418
547
|
}
|
|
419
|
-
//#endregion
|
|
420
|
-
//#region ../shared/dist/logger/index.d.ts
|
|
421
|
-
/**
|
|
422
|
-
* Create a no-op logger for testing
|
|
423
|
-
*
|
|
424
|
-
* Returns a logger that implements the Logger interface but does nothing.
|
|
425
|
-
* Useful for tests that don't need actual logging output.
|
|
426
|
-
*
|
|
427
|
-
* @returns No-op logger instance
|
|
428
|
-
*
|
|
429
|
-
* @example
|
|
430
|
-
* ```typescript
|
|
431
|
-
* // In tests
|
|
432
|
-
* const client = new HttpClient({
|
|
433
|
-
* baseUrl: 'http://test.com',
|
|
434
|
-
* logger: createNoOpLogger() // Optional - tests can enable real logging if needed
|
|
435
|
-
* });
|
|
436
|
-
* ```
|
|
437
|
-
*/
|
|
438
|
-
declare function createNoOpLogger(): Logger;
|
|
439
|
-
/**
|
|
440
|
-
* Get the current logger from AsyncLocalStorage
|
|
441
|
-
*
|
|
442
|
-
* @throws Error if no logger is initialized in the current async context
|
|
443
|
-
* @returns Current logger instance
|
|
444
|
-
*
|
|
445
|
-
* @example
|
|
446
|
-
* ```typescript
|
|
447
|
-
* function someHelperFunction() {
|
|
448
|
-
* const logger = getLogger(); // Automatically has all context!
|
|
449
|
-
* logger.info('Helper called');
|
|
450
|
-
* }
|
|
451
|
-
* ```
|
|
452
|
-
*/
|
|
453
|
-
declare function getLogger(): Logger;
|
|
454
|
-
/**
|
|
455
|
-
* Run a function with a logger stored in AsyncLocalStorage
|
|
456
|
-
*
|
|
457
|
-
* The logger is available to all code within the function via getLogger().
|
|
458
|
-
* This is typically called at request entry points (fetch handler) and when
|
|
459
|
-
* creating child loggers with additional context.
|
|
460
|
-
*
|
|
461
|
-
* @param logger Logger instance to store in context
|
|
462
|
-
* @param fn Function to execute with logger context
|
|
463
|
-
* @returns Result of the function
|
|
464
|
-
*
|
|
465
|
-
* @example
|
|
466
|
-
* ```typescript
|
|
467
|
-
* // At request entry point
|
|
468
|
-
* async fetch(request: Request): Promise<Response> {
|
|
469
|
-
* const logger = createLogger({ component: 'sandbox-do', traceId: 'tr_abc' });
|
|
470
|
-
* return runWithLogger(logger, async () => {
|
|
471
|
-
* return await this.handleRequest(request);
|
|
472
|
-
* });
|
|
473
|
-
* }
|
|
474
|
-
*
|
|
475
|
-
* // When adding operation context
|
|
476
|
-
* async exec(command: string) {
|
|
477
|
-
* const logger = getLogger().child({ operation: 'exec', commandId: 'cmd-123' });
|
|
478
|
-
* return runWithLogger(logger, async () => {
|
|
479
|
-
* logger.info('Command started');
|
|
480
|
-
* await this.executeCommand(command); // Nested calls get the child logger
|
|
481
|
-
* logger.info('Command completed');
|
|
482
|
-
* });
|
|
483
|
-
* }
|
|
484
|
-
* ```
|
|
485
|
-
*/
|
|
486
|
-
declare function runWithLogger<T>(logger: Logger, fn: () => T | Promise<T>): T | Promise<T>;
|
|
487
|
-
/**
|
|
488
|
-
* Create a new logger instance
|
|
489
|
-
*
|
|
490
|
-
* @param context Base context for the logger. Must include 'component'.
|
|
491
|
-
* TraceId will be auto-generated if not provided.
|
|
492
|
-
* @returns New logger instance
|
|
493
|
-
*
|
|
494
|
-
* @example
|
|
495
|
-
* ```typescript
|
|
496
|
-
* // In Durable Object
|
|
497
|
-
* const logger = createLogger({
|
|
498
|
-
* component: 'sandbox-do',
|
|
499
|
-
* traceId: TraceContext.fromHeaders(request.headers) || TraceContext.generate(),
|
|
500
|
-
* sandboxId: this.id
|
|
501
|
-
* });
|
|
502
|
-
*
|
|
503
|
-
* // In Container
|
|
504
|
-
* const logger = createLogger({
|
|
505
|
-
* component: 'container',
|
|
506
|
-
* traceId: TraceContext.fromHeaders(request.headers)!,
|
|
507
|
-
* sessionId: this.id
|
|
508
|
-
* });
|
|
509
|
-
* ```
|
|
510
|
-
*/
|
|
511
|
-
declare function createLogger(context: Partial<LogContext> & {
|
|
512
|
-
component: LogComponent;
|
|
513
|
-
}): Logger;
|
|
514
548
|
//#endregion
|
|
515
549
|
//#region ../shared/dist/request-types.d.ts
|
|
516
550
|
/**
|
|
@@ -1146,6 +1180,7 @@ interface ISandbox {
|
|
|
1146
1180
|
targetDir?: string;
|
|
1147
1181
|
}): Promise<GitCheckoutResult>;
|
|
1148
1182
|
createSession(options?: SessionOptions): Promise<ExecutionSession>;
|
|
1183
|
+
deleteSession(sessionId: string): Promise<SessionDeleteResult>;
|
|
1149
1184
|
createCodeContext(options?: CreateContextOptions): Promise<CodeContext>;
|
|
1150
1185
|
runCode(code: string, options?: RunCodeOptions): Promise<ExecutionResult>;
|
|
1151
1186
|
runCodeStream(code: string, options?: RunCodeOptions): Promise<ReadableStream>;
|
|
@@ -1418,6 +1453,7 @@ interface GitCheckoutRequest extends SessionRequest {
|
|
|
1418
1453
|
* Client for Git repository operations
|
|
1419
1454
|
*/
|
|
1420
1455
|
declare class GitClient extends BaseHttpClient {
|
|
1456
|
+
constructor(options?: HttpClientOptions);
|
|
1421
1457
|
/**
|
|
1422
1458
|
* Clone a Git repository
|
|
1423
1459
|
* @param repoUrl - URL of the Git repository to clone
|
|
@@ -1570,6 +1606,18 @@ interface CreateSessionResponse extends BaseApiResponse {
|
|
|
1570
1606
|
id: string;
|
|
1571
1607
|
message: string;
|
|
1572
1608
|
}
|
|
1609
|
+
/**
|
|
1610
|
+
* Request interface for deleting sessions
|
|
1611
|
+
*/
|
|
1612
|
+
interface DeleteSessionRequest {
|
|
1613
|
+
sessionId: string;
|
|
1614
|
+
}
|
|
1615
|
+
/**
|
|
1616
|
+
* Response interface for deleting sessions
|
|
1617
|
+
*/
|
|
1618
|
+
interface DeleteSessionResponse extends BaseApiResponse {
|
|
1619
|
+
sessionId: string;
|
|
1620
|
+
}
|
|
1573
1621
|
/**
|
|
1574
1622
|
* Client for health checks and utility operations
|
|
1575
1623
|
*/
|
|
@@ -1587,6 +1635,11 @@ declare class UtilityClient extends BaseHttpClient {
|
|
|
1587
1635
|
* @param options - Session configuration (id, env, cwd)
|
|
1588
1636
|
*/
|
|
1589
1637
|
createSession(options: CreateSessionRequest): Promise<CreateSessionResponse>;
|
|
1638
|
+
/**
|
|
1639
|
+
* Delete an execution session
|
|
1640
|
+
* @param sessionId - Session ID to delete
|
|
1641
|
+
*/
|
|
1642
|
+
deleteSession(sessionId: string): Promise<DeleteSessionResponse>;
|
|
1590
1643
|
/**
|
|
1591
1644
|
* Get the container version
|
|
1592
1645
|
* Returns the version embedded in the Docker image during build
|
|
@@ -1764,6 +1817,17 @@ declare class Sandbox<Env = unknown> extends Container<Env> implements ISandbox
|
|
|
1764
1817
|
* @returns ExecutionSession wrapper bound to the session
|
|
1765
1818
|
*/
|
|
1766
1819
|
getSession(sessionId: string): Promise<ExecutionSession>;
|
|
1820
|
+
/**
|
|
1821
|
+
* Delete an execution session
|
|
1822
|
+
* Cleans up session resources and removes it from the container
|
|
1823
|
+
* Note: Cannot delete the default session. To reset the default session,
|
|
1824
|
+
* use sandbox.destroy() to terminate the entire sandbox.
|
|
1825
|
+
*
|
|
1826
|
+
* @param sessionId - The ID of the session to delete
|
|
1827
|
+
* @returns Result with success status, sessionId, and timestamp
|
|
1828
|
+
* @throws Error if attempting to delete the default session
|
|
1829
|
+
*/
|
|
1830
|
+
deleteSession(sessionId: string): Promise<SessionDeleteResult>;
|
|
1767
1831
|
/**
|
|
1768
1832
|
* Internal helper to create ExecutionSession wrapper for a given sessionId
|
|
1769
1833
|
* Used by both createSession and getSession
|
|
@@ -1885,5 +1949,5 @@ declare function asyncIterableToSSEStream<T>(events: AsyncIterable<T>, options?:
|
|
|
1885
1949
|
serialize?: (event: T) => string;
|
|
1886
1950
|
}): ReadableStream<Uint8Array>;
|
|
1887
1951
|
//#endregion
|
|
1888
|
-
export { type BaseApiResponse, type BaseExecOptions, type ChartData, type CodeContext, CodeInterpreter, CommandClient, type ExecuteResponse as CommandExecuteResponse, type CommandsResponse, type ContainerStub, ContextCreateResult, ContextDeleteResult, ContextListResult, type CreateContextOptions, DeleteFileRequest, DeleteFileResult, EnvSetResult, type ErrorResponse, type ExecEvent, type ExecOptions, type ExecResult, type ExecuteRequest, Execution, type ExecutionCallbacks, type ExecutionError, type ExecutionResult, ExecutionSession, type ExposePortRequest, type FileChunk, FileClient, FileExistsRequest, FileExistsResult, FileInfo, type FileMetadata, type FileOperationRequest, type FileStreamEvent, type GitCheckoutRequest, type GitCheckoutResult, GitClient, HealthCheckResult, type ISandbox, type InterpreterClient, InterpreterHealthResult, ListFilesOptions, ListFilesResult, type LogContext, type LogEvent, type LogLevel, LogLevel as LogLevelEnum, type Logger, type MkdirRequest, MkdirResult, MoveFileRequest, MoveFileResult, type OutputMessage, type PingResponse, PortClient, type PortCloseResult, type PortExposeResult, type PortListResult, PortStatusResult, type Process, type ProcessCleanupResult, ProcessClient, type ProcessInfoResult, type ProcessKillResult, type ProcessListResult, type ProcessLogsResult, type ProcessOptions, type ProcessStartResult, type ProcessStatus, type ReadFileRequest, ReadFileResult, RenameFileRequest, RenameFileResult, type RequestConfig, type ResponseHandler, type Result, ResultImpl, type RouteInfo, type RunCodeOptions, Sandbox, SandboxClient, type HttpClientOptions as SandboxClientOptions, type SandboxEnv, SandboxOptions, SessionCreateRequest, SessionCreateResult, SessionDeleteRequest, SessionDeleteResult, SessionOptions, type SessionRequest, ShutdownResult, type StartProcessRequest, type StreamOptions, TraceContext, type UnexposePortRequest, UtilityClient, type WriteFileRequest, WriteFileResult, asyncIterableToSSEStream, collectFile, createLogger, createNoOpLogger, getLogger, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyToSandbox, responseToAsyncIterable, runWithLogger, streamFile };
|
|
1952
|
+
export { type BaseApiResponse, type BaseExecOptions, type ChartData, type CodeContext, CodeInterpreter, CommandClient, type ExecuteResponse as CommandExecuteResponse, type CommandsResponse, type ContainerStub, ContextCreateResult, ContextDeleteResult, ContextListResult, type CreateContextOptions, type CreateSessionRequest, type CreateSessionResponse, DeleteFileRequest, DeleteFileResult, type DeleteSessionRequest, type DeleteSessionResponse, EnvSetResult, type ErrorResponse, type ExecEvent, type ExecOptions, type ExecResult, type ExecuteRequest, Execution, type ExecutionCallbacks, type ExecutionError, type ExecutionResult, ExecutionSession, type ExposePortRequest, type FileChunk, FileClient, FileExistsRequest, FileExistsResult, FileInfo, type FileMetadata, type FileOperationRequest, type FileStreamEvent, type GitCheckoutRequest, type GitCheckoutResult, GitClient, GitLogger, HealthCheckResult, type ISandbox, type InterpreterClient, InterpreterHealthResult, ListFilesOptions, ListFilesResult, type LogContext, type LogEvent, type LogLevel, LogLevel as LogLevelEnum, type Logger, type MkdirRequest, MkdirResult, MoveFileRequest, MoveFileResult, type OutputMessage, type PingResponse, PortClient, type PortCloseResult, type PortExposeResult, type PortListResult, PortStatusResult, type Process, type ProcessCleanupResult, ProcessClient, type ProcessInfoResult, type ProcessKillResult, type ProcessListResult, type ProcessLogsResult, type ProcessOptions, type ProcessStartResult, type ProcessStatus, type ReadFileRequest, ReadFileResult, RenameFileRequest, RenameFileResult, type RequestConfig, type ResponseHandler, type Result, ResultImpl, type RouteInfo, type RunCodeOptions, Sandbox, SandboxClient, type HttpClientOptions as SandboxClientOptions, type SandboxEnv, SandboxOptions, SessionCreateRequest, SessionCreateResult, SessionDeleteRequest, SessionDeleteResult, SessionOptions, type SessionRequest, ShutdownResult, type StartProcessRequest, type StreamOptions, TraceContext, type UnexposePortRequest, UtilityClient, type WriteFileRequest, WriteFileResult, asyncIterableToSSEStream, collectFile, createLogger, createNoOpLogger, getLogger, getSandbox, isExecResult, isProcess, isProcessStatus, parseSSEStream, proxyToSandbox, redactCredentials, responseToAsyncIterable, runWithLogger, sanitizeGitData, streamFile };
|
|
1889
1953
|
//# sourceMappingURL=index.d.ts.map
|