matchlock-sdk 0.1.22

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.
Files changed (12) hide show
  1. package/README.md +57 -0
  2. package/dist/builder.d.ts +37 -0
  3. package/dist/builder.js +199 -0
  4. package/dist/client.d.ts +65 -0
  5. package/dist/client.js +966 -0
  6. package/dist/errors.d.ts +20 -0
  7. package/dist/errors.js +39 -0
  8. package/dist/index.d.ts +5 -0
  9. package/dist/index.js +33 -0
  10. package/dist/types.d.ts +153 -0
  11. package/dist/types.js +23 -0
  12. package/package.json +33 -0
package/dist/errors.d.ts ADDED
@@ -0,0 +1,20 @@
1
+ export declare class MatchlockError extends Error {
2
+ constructor(message: string);
3
+ }
4
+ export declare class RPCError extends MatchlockError {
5
+ static readonly PARSE_ERROR = -32700;
6
+ static readonly INVALID_REQUEST = -32600;
7
+ static readonly METHOD_NOT_FOUND = -32601;
8
+ static readonly INVALID_PARAMS = -32602;
9
+ static readonly INTERNAL_ERROR = -32603;
10
+ static readonly VM_FAILED = -32000;
11
+ static readonly EXEC_FAILED = -32001;
12
+ static readonly FILE_FAILED = -32002;
13
+ static readonly CANCELLED = -32003;
14
+ readonly code: number;
15
+ readonly rpcMessage: string;
16
+ constructor(code: number, message: string);
17
+ isVMError(): boolean;
18
+ isExecError(): boolean;
19
+ isFileError(): boolean;
20
+ }
package/dist/errors.js ADDED
@@ -0,0 +1,39 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.RPCError = exports.MatchlockError = void 0;
4
+ class MatchlockError extends Error {
5
+ constructor(message) {
6
+ super(message);
7
+ this.name = "MatchlockError";
8
+ }
9
+ }
10
+ exports.MatchlockError = MatchlockError;
11
+ class RPCError extends MatchlockError {
12
+ static PARSE_ERROR = -32700;
13
+ static INVALID_REQUEST = -32600;
14
+ static METHOD_NOT_FOUND = -32601;
15
+ static INVALID_PARAMS = -32602;
16
+ static INTERNAL_ERROR = -32603;
17
+ static VM_FAILED = -32000;
18
+ static EXEC_FAILED = -32001;
19
+ static FILE_FAILED = -32002;
20
+ static CANCELLED = -32003;
21
+ code;
22
+ rpcMessage;
23
+ constructor(code, message) {
24
+ super(`[${code}] ${message}`);
25
+ this.name = "RPCError";
26
+ this.code = code;
27
+ this.rpcMessage = message;
28
+ }
29
+ isVMError() {
30
+ return this.code === RPCError.VM_FAILED;
31
+ }
32
+ isExecError() {
33
+ return this.code === RPCError.EXEC_FAILED;
34
+ }
35
+ isFileError() {
36
+ return this.code === RPCError.FILE_FAILED;
37
+ }
38
+ }
39
+ exports.RPCError = RPCError;
package/dist/index.d.ts ADDED
@@ -0,0 +1,5 @@
1
+ export { Client, defaultConfig } from "./client";
2
+ export { Sandbox, createSandbox } from "./builder";
3
+ export { MatchlockError, RPCError } from "./errors";
4
+ export { VFS_HOOK_ACTION_ALLOW, VFS_HOOK_ACTION_BLOCK, VFS_HOOK_OP_STAT, VFS_HOOK_OP_READDIR, VFS_HOOK_OP_OPEN, VFS_HOOK_OP_CREATE, VFS_HOOK_OP_MKDIR, VFS_HOOK_OP_CHMOD, VFS_HOOK_OP_REMOVE, VFS_HOOK_OP_REMOVE_ALL, VFS_HOOK_OP_RENAME, VFS_HOOK_OP_SYMLINK, VFS_HOOK_OP_READLINK, VFS_HOOK_OP_READ, VFS_HOOK_OP_WRITE, VFS_HOOK_OP_CLOSE, VFS_HOOK_OP_SYNC, VFS_HOOK_OP_TRUNCATE, VFS_HOOK_PHASE_BEFORE, VFS_HOOK_PHASE_AFTER, } from "./types";
5
+ export type { BinaryLike, Config, CreateOptions, ExecOptions, ExecResult, ExecStreamOptions, ExecStreamResult, FileInfo, HostIPMapping, ImageConfig, MountConfig, PortForward, PortForwardBinding, RequestOptions, Secret, StreamWriter, VFSActionHookFunc, VFSActionRequest, VFSDangerousHookFunc, VFSHookAction, VFSHookEvent, VFSHookFunc, VFSHookOp, VFSHookPhase, VFSHookRule, VFSInterceptionConfig, VFSMutateHookFunc, VFSMutateRequest, } from "./types";
package/dist/index.js ADDED
@@ -0,0 +1,33 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.VFS_HOOK_PHASE_AFTER = exports.VFS_HOOK_PHASE_BEFORE = exports.VFS_HOOK_OP_TRUNCATE = exports.VFS_HOOK_OP_SYNC = exports.VFS_HOOK_OP_CLOSE = exports.VFS_HOOK_OP_WRITE = exports.VFS_HOOK_OP_READ = exports.VFS_HOOK_OP_READLINK = exports.VFS_HOOK_OP_SYMLINK = exports.VFS_HOOK_OP_RENAME = exports.VFS_HOOK_OP_REMOVE_ALL = exports.VFS_HOOK_OP_REMOVE = exports.VFS_HOOK_OP_CHMOD = exports.VFS_HOOK_OP_MKDIR = exports.VFS_HOOK_OP_CREATE = exports.VFS_HOOK_OP_OPEN = exports.VFS_HOOK_OP_READDIR = exports.VFS_HOOK_OP_STAT = exports.VFS_HOOK_ACTION_BLOCK = exports.VFS_HOOK_ACTION_ALLOW = exports.RPCError = exports.MatchlockError = exports.createSandbox = exports.Sandbox = exports.defaultConfig = exports.Client = void 0;
4
+ var client_1 = require("./client");
5
+ Object.defineProperty(exports, "Client", { enumerable: true, get: function () { return client_1.Client; } });
6
+ Object.defineProperty(exports, "defaultConfig", { enumerable: true, get: function () { return client_1.defaultConfig; } });
7
+ var builder_1 = require("./builder");
8
+ Object.defineProperty(exports, "Sandbox", { enumerable: true, get: function () { return builder_1.Sandbox; } });
9
+ Object.defineProperty(exports, "createSandbox", { enumerable: true, get: function () { return builder_1.createSandbox; } });
10
+ var errors_1 = require("./errors");
11
+ Object.defineProperty(exports, "MatchlockError", { enumerable: true, get: function () { return errors_1.MatchlockError; } });
12
+ Object.defineProperty(exports, "RPCError", { enumerable: true, get: function () { return errors_1.RPCError; } });
13
+ var types_1 = require("./types");
14
+ Object.defineProperty(exports, "VFS_HOOK_ACTION_ALLOW", { enumerable: true, get: function () { return types_1.VFS_HOOK_ACTION_ALLOW; } });
15
+ Object.defineProperty(exports, "VFS_HOOK_ACTION_BLOCK", { enumerable: true, get: function () { return types_1.VFS_HOOK_ACTION_BLOCK; } });
16
+ Object.defineProperty(exports, "VFS_HOOK_OP_STAT", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_STAT; } });
17
+ Object.defineProperty(exports, "VFS_HOOK_OP_READDIR", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_READDIR; } });
18
+ Object.defineProperty(exports, "VFS_HOOK_OP_OPEN", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_OPEN; } });
19
+ Object.defineProperty(exports, "VFS_HOOK_OP_CREATE", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_CREATE; } });
20
+ Object.defineProperty(exports, "VFS_HOOK_OP_MKDIR", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_MKDIR; } });
21
+ Object.defineProperty(exports, "VFS_HOOK_OP_CHMOD", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_CHMOD; } });
22
+ Object.defineProperty(exports, "VFS_HOOK_OP_REMOVE", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_REMOVE; } });
23
+ Object.defineProperty(exports, "VFS_HOOK_OP_REMOVE_ALL", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_REMOVE_ALL; } });
24
+ Object.defineProperty(exports, "VFS_HOOK_OP_RENAME", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_RENAME; } });
25
+ Object.defineProperty(exports, "VFS_HOOK_OP_SYMLINK", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_SYMLINK; } });
26
+ Object.defineProperty(exports, "VFS_HOOK_OP_READLINK", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_READLINK; } });
27
+ Object.defineProperty(exports, "VFS_HOOK_OP_READ", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_READ; } });
28
+ Object.defineProperty(exports, "VFS_HOOK_OP_WRITE", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_WRITE; } });
29
+ Object.defineProperty(exports, "VFS_HOOK_OP_CLOSE", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_CLOSE; } });
30
+ Object.defineProperty(exports, "VFS_HOOK_OP_SYNC", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_SYNC; } });
31
+ Object.defineProperty(exports, "VFS_HOOK_OP_TRUNCATE", { enumerable: true, get: function () { return types_1.VFS_HOOK_OP_TRUNCATE; } });
32
+ Object.defineProperty(exports, "VFS_HOOK_PHASE_BEFORE", { enumerable: true, get: function () { return types_1.VFS_HOOK_PHASE_BEFORE; } });
33
+ Object.defineProperty(exports, "VFS_HOOK_PHASE_AFTER", { enumerable: true, get: function () { return types_1.VFS_HOOK_PHASE_AFTER; } });
package/dist/types.d.ts ADDED
@@ -0,0 +1,153 @@
1
+ import type { Client } from "./client";
2
+ export declare const VFS_HOOK_PHASE_BEFORE = "before";
3
+ export declare const VFS_HOOK_PHASE_AFTER = "after";
4
+ export declare const VFS_HOOK_ACTION_ALLOW = "allow";
5
+ export declare const VFS_HOOK_ACTION_BLOCK = "block";
6
+ export declare const VFS_HOOK_OP_STAT = "stat";
7
+ export declare const VFS_HOOK_OP_READDIR = "readdir";
8
+ export declare const VFS_HOOK_OP_OPEN = "open";
9
+ export declare const VFS_HOOK_OP_CREATE = "create";
10
+ export declare const VFS_HOOK_OP_MKDIR = "mkdir";
11
+ export declare const VFS_HOOK_OP_CHMOD = "chmod";
12
+ export declare const VFS_HOOK_OP_REMOVE = "remove";
13
+ export declare const VFS_HOOK_OP_REMOVE_ALL = "remove_all";
14
+ export declare const VFS_HOOK_OP_RENAME = "rename";
15
+ export declare const VFS_HOOK_OP_SYMLINK = "symlink";
16
+ export declare const VFS_HOOK_OP_READLINK = "readlink";
17
+ export declare const VFS_HOOK_OP_READ = "read";
18
+ export declare const VFS_HOOK_OP_WRITE = "write";
19
+ export declare const VFS_HOOK_OP_CLOSE = "close";
20
+ export declare const VFS_HOOK_OP_SYNC = "sync";
21
+ export declare const VFS_HOOK_OP_TRUNCATE = "truncate";
22
+ export type VFSHookPhase = "" | "before" | "after";
23
+ export type VFSHookOp = "stat" | "readdir" | "open" | "create" | "mkdir" | "chmod" | "remove" | "remove_all" | "rename" | "symlink" | "readlink" | "read" | "write" | "close" | "sync" | "truncate";
24
+ export type VFSHookAction = "allow" | "block" | (string & {});
25
+ export interface Config {
26
+ binaryPath?: string;
27
+ useSudo?: boolean;
28
+ }
29
+ export interface HostIPMapping {
30
+ host: string;
31
+ ip: string;
32
+ }
33
+ export interface MountConfig {
34
+ type?: string;
35
+ hostPath?: string;
36
+ readonly?: boolean;
37
+ }
38
+ export interface Secret {
39
+ name: string;
40
+ value: string;
41
+ hosts?: string[];
42
+ }
43
+ export interface ImageConfig {
44
+ user?: string;
45
+ workingDir?: string;
46
+ entrypoint?: string[];
47
+ cmd?: string[];
48
+ env?: Record<string, string>;
49
+ }
50
+ export interface PortForward {
51
+ localPort: number;
52
+ remotePort: number;
53
+ }
54
+ export interface PortForwardBinding {
55
+ address: string;
56
+ localPort: number;
57
+ remotePort: number;
58
+ }
59
+ export interface VFSHookEvent {
60
+ op: string;
61
+ path: string;
62
+ size: number;
63
+ mode: number;
64
+ uid: number;
65
+ gid: number;
66
+ }
67
+ export interface VFSMutateRequest {
68
+ path: string;
69
+ size: number;
70
+ mode: number;
71
+ uid: number;
72
+ gid: number;
73
+ }
74
+ export interface VFSActionRequest {
75
+ op: string;
76
+ path: string;
77
+ size: number;
78
+ mode: number;
79
+ uid: number;
80
+ gid: number;
81
+ }
82
+ export type BinaryLike = string | Buffer | Uint8Array | ArrayBuffer;
83
+ export type VFSHookFunc = (event: VFSHookEvent) => void | Promise<void>;
84
+ export type VFSDangerousHookFunc = (client: Client, event: VFSHookEvent) => void | Promise<void>;
85
+ export type VFSMutateHookFunc = (request: VFSMutateRequest) => BinaryLike | null | undefined | Promise<BinaryLike | null | undefined>;
86
+ export type VFSActionHookFunc = (request: VFSActionRequest) => VFSHookAction | Promise<VFSHookAction>;
87
+ export interface VFSHookRule {
88
+ name?: string;
89
+ phase?: VFSHookPhase;
90
+ ops?: VFSHookOp[];
91
+ path?: string;
92
+ action?: VFSHookAction;
93
+ timeoutMs?: number;
94
+ hook?: VFSHookFunc;
95
+ dangerousHook?: VFSDangerousHookFunc;
96
+ mutateHook?: VFSMutateHookFunc;
97
+ actionHook?: VFSActionHookFunc;
98
+ }
99
+ export interface VFSInterceptionConfig {
100
+ emitEvents?: boolean;
101
+ rules?: VFSHookRule[];
102
+ }
103
+ export interface CreateOptions {
104
+ image?: string;
105
+ privileged?: boolean;
106
+ cpus?: number;
107
+ memoryMb?: number;
108
+ diskSizeMb?: number;
109
+ timeoutSeconds?: number;
110
+ allowedHosts?: string[];
111
+ addHosts?: HostIPMapping[];
112
+ blockPrivateIPs?: boolean;
113
+ blockPrivateIPsSet?: boolean;
114
+ mounts?: Record<string, MountConfig>;
115
+ env?: Record<string, string>;
116
+ secrets?: Secret[];
117
+ workspace?: string;
118
+ vfsInterception?: VFSInterceptionConfig;
119
+ dnsServers?: string[];
120
+ hostname?: string;
121
+ networkMtu?: number;
122
+ portForwards?: PortForward[];
123
+ portForwardAddresses?: string[];
124
+ imageConfig?: ImageConfig;
125
+ }
126
+ export interface ExecResult {
127
+ exitCode: number;
128
+ stdout: string;
129
+ stderr: string;
130
+ durationMs: number;
131
+ }
132
+ export interface ExecStreamResult {
133
+ exitCode: number;
134
+ durationMs: number;
135
+ }
136
+ export interface FileInfo {
137
+ name: string;
138
+ size: number;
139
+ mode: number;
140
+ isDir: boolean;
141
+ }
142
+ export type StreamWriter = NodeJS.WritableStream | ((chunk: Buffer) => void | Promise<void>);
143
+ export interface RequestOptions {
144
+ signal?: AbortSignal;
145
+ timeoutMs?: number;
146
+ }
147
+ export interface ExecOptions extends RequestOptions {
148
+ workingDir?: string;
149
+ }
150
+ export interface ExecStreamOptions extends ExecOptions {
151
+ stdout?: StreamWriter;
152
+ stderr?: StreamWriter;
153
+ }
package/dist/types.js ADDED
@@ -0,0 +1,23 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.VFS_HOOK_OP_TRUNCATE = exports.VFS_HOOK_OP_SYNC = exports.VFS_HOOK_OP_CLOSE = exports.VFS_HOOK_OP_WRITE = exports.VFS_HOOK_OP_READ = exports.VFS_HOOK_OP_READLINK = exports.VFS_HOOK_OP_SYMLINK = exports.VFS_HOOK_OP_RENAME = exports.VFS_HOOK_OP_REMOVE_ALL = exports.VFS_HOOK_OP_REMOVE = exports.VFS_HOOK_OP_CHMOD = exports.VFS_HOOK_OP_MKDIR = exports.VFS_HOOK_OP_CREATE = exports.VFS_HOOK_OP_OPEN = exports.VFS_HOOK_OP_READDIR = exports.VFS_HOOK_OP_STAT = exports.VFS_HOOK_ACTION_BLOCK = exports.VFS_HOOK_ACTION_ALLOW = exports.VFS_HOOK_PHASE_AFTER = exports.VFS_HOOK_PHASE_BEFORE = void 0;
4
+ exports.VFS_HOOK_PHASE_BEFORE = "before";
5
+ exports.VFS_HOOK_PHASE_AFTER = "after";
6
+ exports.VFS_HOOK_ACTION_ALLOW = "allow";
7
+ exports.VFS_HOOK_ACTION_BLOCK = "block";
8
+ exports.VFS_HOOK_OP_STAT = "stat";
9
+ exports.VFS_HOOK_OP_READDIR = "readdir";
10
+ exports.VFS_HOOK_OP_OPEN = "open";
11
+ exports.VFS_HOOK_OP_CREATE = "create";
12
+ exports.VFS_HOOK_OP_MKDIR = "mkdir";
13
+ exports.VFS_HOOK_OP_CHMOD = "chmod";
14
+ exports.VFS_HOOK_OP_REMOVE = "remove";
15
+ exports.VFS_HOOK_OP_REMOVE_ALL = "remove_all";
16
+ exports.VFS_HOOK_OP_RENAME = "rename";
17
+ exports.VFS_HOOK_OP_SYMLINK = "symlink";
18
+ exports.VFS_HOOK_OP_READLINK = "readlink";
19
+ exports.VFS_HOOK_OP_READ = "read";
20
+ exports.VFS_HOOK_OP_WRITE = "write";
21
+ exports.VFS_HOOK_OP_CLOSE = "close";
22
+ exports.VFS_HOOK_OP_SYNC = "sync";
23
+ exports.VFS_HOOK_OP_TRUNCATE = "truncate";
package/package.json ADDED
@@ -0,0 +1,33 @@
1
+ {
2
+ "name": "matchlock-sdk",
3
+ "version": "0.1.22",
4
+ "description": "TypeScript SDK for Matchlock sandboxes",
5
+ "license": "MIT",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "https://github.com/jingkaihe/matchlock",
9
+ "directory": "sdk/typescript"
10
+ },
11
+ "main": "dist/index.js",
12
+ "types": "dist/index.d.ts",
13
+ "files": [
14
+ "dist"
15
+ ],
16
+ "engines": {
17
+ "node": ">=22"
18
+ },
19
+ "scripts": {
20
+ "build": "tsc -p tsconfig.build.json",
21
+ "typecheck": "tsc -p tsconfig.json --noEmit",
22
+ "test": "vitest run",
23
+ "test:watch": "vitest"
24
+ },
25
+ "dependencies": {
26
+ "minimatch": "^10.0.3"
27
+ },
28
+ "devDependencies": {
29
+ "@types/node": "^22.13.4",
30
+ "typescript": "^5.8.2",
31
+ "vitest": "^3.0.6"
32
+ }
33
+ }