@cloudflare/workspace 0.0.0-alpha.2 → 0.0.0-alpha.4

package/README.md

@@ -64,6 +64,63 @@ export default {
 } satisfies ExportedHandler<Env>;
 ```
 
+## Observability
+
+The package emits one span per documented operation through an optional
+observer hook. Pass an observer to the `Workspace` constructor:
+
+```ts
+import { Workspace, type WorkspaceObserver } from "@cloudflare/workspace";
+
+const observer: WorkspaceObserver = {
+  async span(name, attributes, run) {
+    // Wrap `run` however your tracing backend wants. The Cloudflare
+    // runtime, OpenTelemetry, and a plain console.log adapter all fit
+    // the same shape.
+    return run({ setAttribute: () => {} });
+  },
+};
+
+const ws = new Workspace({
+  storage: this.ctx.storage,
+  backends: [...],
+  observer,
+});
+```
+
+The observer's `span(name, attributes, run)` wraps each operation. It
+starts a span, runs the callback, and ends the span when the callback
+returns or its promise settles. Errors thrown by the work record
+`error.name` and `error.message` and propagate.
+
+The span names the package emits today:
+
+- `workspace.connect` — one per `connect()` attempt against a single
+  backend. Tagged with `workspace.backend.id`.
+- `workspace.sync.push` / `workspace.sync.pull` — one per sync call.
+  Tagged with the entry counts (`workspace.sync.pushed`,
+  `workspace.sync.applied`, `workspace.sync.skipped`).
+- `workspace.shell.exec` — the full exec bracket from the
+  `WorkspaceStub`. Contains `workspace.sync.push`,
+  `workspace.shell.exec.spawn`, and `workspace.sync.pull` as nested
+  children. Tagged with `workspace.shell.exit_code`,
+  `workspace.shell.pushed`, `workspace.shell.pulled`, and
+  `workspace.shell.skipped`.
+- `workspace.fs.<op>` — one per filesystem call routed through the
+  stub (`readFile`, `writeFile`, `stat`, `readdir`, `find`, `ls`,
+  `grep`, `mkdir`, `rm`). Tagged with `workspace.fs.path` and, where
+  meaningful, `workspace.fs.entries` or `workspace.fs.matches`.
+
+Attribute values are restricted to `boolean | number | string` so the
+same observer shape works against the Cloudflare runtime's built-in
+`ctx.tracing.enterSpan(...)` API, OpenTelemetry, or a recording test
+observer. Adapter packages for the Cloudflare runtime and for
+OpenTelemetry are forthcoming.
+
+The default is a no-op observer with no allocation or async overhead
+beyond what the callback itself does, so the package has no
+observability cost when callers do not opt in.
+
 ## Stub disposal
 
 capnweb does not garbage-collect remote stubs. On the long-lived

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { _ as Database, a as SQLiteWorkspaceProviderOptions, c as WriteFileOptions, d as ReadFileOptions, f as WorkspaceDirentResult, g as WorkspaceFoundEntry, h as WorkspaceGrepMatch, i as SQLiteWorkspaceProvider, l as WorkspaceStatResult, m as GrepOptions, n as SkippedEntry, o as WorkspaceFilesystem, p as MkdirOptions, r as ChangeEntry, s as WriteFileContent, t as ApplyResult, u as RmOptions, v as DurableObjectStorageLike } from "./shared-RIdME5uo.js";
+import { a as noopObserver, i as WorkspaceSpan, n as WorkspaceAttributes, r as WorkspaceObserver, t as WorkspaceAttributeValue } from "./shared-DYgflRlD.js";
 import { RpcTarget } from "capnweb";
 import { RpcTarget as RpcTarget$1, WorkerEntrypoint } from "cloudflare:workers";
 
@@ -261,7 +262,7 @@ interface Sync {
 }
 declare class WorkspaceShell {
   #private;
-  constructor(shell: ShellRPC, sync: Sync);
+  constructor(shell: ShellRPC, sync: Sync, observer?: WorkspaceObserver);
   exec(command: string): Promise<ExecHandle<undefined>>;
   exec(command: string, options: ExecOptions<undefined>): Promise<ExecHandle<undefined>>;
   exec(command: string, options: ExecOptions<"utf8">): Promise<ExecHandle<"utf8">>;
@@ -280,6 +281,7 @@ interface WorkspaceOptions {
   now?: () => number;
   sessionId?: string;
   mounts?: Record<string, MountValue>;
+  observer?: WorkspaceObserver;
   reconnect?: ReconnectOptions;
 }
 interface ReconnectOptions {
@@ -293,6 +295,7 @@ declare class Workspace {
   ensureMountsIndexed(): Promise<void>;
   mounts(): Map<string, Mount>;
   get db(): Database;
+  get observer(): WorkspaceObserver;
   get fs(): WorkspaceFilesystem;
   /**
    * Underlying dofs `SQLiteWorkspaceProvider` over the local store.
@@ -380,5 +383,5 @@ declare class WorkspaceStub extends RpcTarget {
   get shell(): WorkspaceShellStub;
 }
 //#endregion
-export { type ApplyResult, type BackendHandle, CloudflareContainerBackend, type CloudflareContainerBackendOptions, type DurableObjectStorageLike, type EagerMount, type ExecEncoding, type ExecHandle, type ExecOptions, type ExecResult, type GetExecOptions, type IWorkspaceContainerAPI, type KillSignal, type Mount, type MountBase, type MountContext, type MountFactory, type MountWriteAPI, R2Bucket, type R2BucketBinding, type R2BucketOptions, SQLiteWorkspaceProvider, type SQLiteWorkspaceProviderOptions, type SkippedEntry, TestBackend, type TestBackendOptions, Workspace, type WorkspaceBackend, WorkspaceContainerAPI, type WorkspaceExecEvent, WorkspaceExecHandleStub, type WorkspaceExecOptions, type WorkspaceExecResult, WorkspaceFilesystemStub, type WorkspaceOptions, WorkspaceProxy, type WorkspaceProxyProps, type WorkspaceRef, WorkspaceShell, WorkspaceShellStub, WorkspaceStub, withWorkspaceContainer };
+export { type ApplyResult, type BackendHandle, CloudflareContainerBackend, type CloudflareContainerBackendOptions, type DurableObjectStorageLike, type EagerMount, type ExecEncoding, type ExecHandle, type ExecOptions, type ExecResult, type GetExecOptions, type IWorkspaceContainerAPI, type KillSignal, type Mount, type MountBase, type MountContext, type MountFactory, type MountWriteAPI, R2Bucket, type R2BucketBinding, type R2BucketOptions, SQLiteWorkspaceProvider, type SQLiteWorkspaceProviderOptions, type SkippedEntry, TestBackend, type TestBackendOptions, Workspace, type WorkspaceAttributeValue, type WorkspaceAttributes, type WorkspaceBackend, WorkspaceContainerAPI, type WorkspaceExecEvent, WorkspaceExecHandleStub, type WorkspaceExecOptions, type WorkspaceExecResult, WorkspaceFilesystemStub, type WorkspaceObserver, type WorkspaceOptions, WorkspaceProxy, type WorkspaceProxyProps, type WorkspaceRef, WorkspaceShell, WorkspaceShellStub, type WorkspaceSpan, WorkspaceStub, noopObserver, withWorkspaceContainer };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -2035,6 +2035,63 @@ function R2Bucket(bucket, options = {}) {
 	};
 }
 //#endregion
+//#region src/observe.ts
+const NOOP_SPAN = { setAttribute() {} };
+/**
+* Observer that does no work. Used when the caller does not pass one.
+* Calling `span(...)` returns the callback's promise directly, with no
+* extra `await` and no allocation beyond what the callback itself does.
+*/
+const noopObserver = { span(_name, _attributes, run) {
+	return run(NOOP_SPAN);
+} };
+/**
+* Internal helper: wraps `run` with `observer.span(...)`, applies any
+* `undefined`-filtered attributes the work produces on settlement, and
+* records error details on rejection before re-throwing.
+*
+* The `finalize` callback runs with the result (on success) or the
+* thrown error (on failure) and is the single place call sites attach
+* post-hoc attributes like byte counts, exit codes, or applied counts.
+* Both branches are wrapped in try/catch so a buggy `finalize` does
+* not mask the original outcome.
+*/
+function withSpan(observer, name, attributes, run, finalize) {
+	return observer.span(name, attributes, async (span) => {
+		try {
+			const value = await run();
+			if (finalize) try {
+				finalize(span, {
+					ok: true,
+					value
+				});
+			} catch {}
+			return value;
+		} catch (error) {
+			recordError(span, error);
+			if (finalize) try {
+				finalize(span, {
+					ok: false,
+					error
+				});
+			} catch {}
+			throw error;
+		}
+	});
+}
+/**
+* Records `error.message` and `error.name` on `span`. Adapters that
+* want richer error reporting can subscribe to the underlying span
+* system directly; the workspace itself only forwards what the
+* Cloudflare `Span` surface accepts.
+*/
+function recordError(span, error) {
+	if (error instanceof Error) {
+		span.setAttribute("error.name", error.name);
+		span.setAttribute("error.message", error.message);
+	} else span.setAttribute("error.message", String(error));
+}
+//#endregion
 //#region src/proxy.ts
 var WorkspaceProxy = class extends WorkerEntrypoint {
 	async fetch(request) {
@@ -2054,20 +2111,28 @@ var WorkspaceProxy = class extends WorkerEntrypoint {
 var WorkspaceShell = class {
 	#shell;
 	#sync;
-	constructor(shell, sync) {
+	#observer;
+	constructor(shell, sync, observer = noopObserver) {
 		this.#shell = shell;
 		this.#sync = sync;
+		this.#observer = observer;
 	}
 	async exec(command, options = {}) {
 		let pushed = 0;
 		try {
 			pushed = await this.#sync.push();
 		} catch {}
-		const envelope = await this.#shell.exec({
+		const envelope = await withSpan(this.#observer, "workspace.shell.exec.spawn", {
+			"workspace.shell.cwd": options.cwd,
+			"workspace.shell.timeout_ms": options.timeoutMs,
+			"workspace.shell.id": options.id
+		}, () => this.#shell.exec({
 			command,
 			id: options.id,
 			cwd: options.cwd,
 			timeoutMs: options.timeoutMs
+		}), (span, outcome) => {
+			if (outcome.ok) span.setAttribute("workspace.shell.id", outcome.value.id);
 		});
 		const events = disposeOnDone$1(envelope.events, () => maybeDispose$1(envelope));
 		return wrapHandle(this.#shell, this.#sync, envelope.id, events, options.encoding, pushed);
@@ -2263,31 +2328,52 @@ var WorkspaceFilesystemStub = class extends RpcTarget {
 		untrackStub(this);
 	}
 	readFile(path, optionsOrEncoding) {
-		return this.#ws.fs.readFile(path, optionsOrEncoding);
+		return withSpan(this.#ws.observer, "workspace.fs.readFile", { "workspace.fs.path": path }, () => this.#ws.fs.readFile(path, optionsOrEncoding));
 	}
 	stat(path) {
-		return this.#ws.fs.stat(path);
+		return withSpan(this.#ws.observer, "workspace.fs.stat", { "workspace.fs.path": path }, () => this.#ws.fs.stat(path));
 	}
 	readdir(path) {
-		return this.#ws.fs.readdir(path);
+		return withSpan(this.#ws.observer, "workspace.fs.readdir", { "workspace.fs.path": path }, () => this.#ws.fs.readdir(path), (span, outcome) => {
+			if (outcome.ok) span.setAttribute("workspace.fs.entries", outcome.value.length);
+		});
 	}
 	find(directory, pattern) {
-		return this.#ws.fs.find(directory, pattern);
+		return withSpan(this.#ws.observer, "workspace.fs.find", {
+			"workspace.fs.path": directory,
+			"workspace.fs.pattern": pattern
+		}, () => this.#ws.fs.find(directory, pattern), (span, outcome) => {
+			if (outcome.ok) span.setAttribute("workspace.fs.matches", outcome.value.length);
+		});
 	}
 	ls(prefix) {
-		return this.#ws.fs.ls(prefix);
+		return withSpan(this.#ws.observer, "workspace.fs.ls", { "workspace.fs.path": prefix }, () => this.#ws.fs.ls(prefix), (span, outcome) => {
+			if (outcome.ok) span.setAttribute("workspace.fs.entries", outcome.value.length);
+		});
 	}
 	grep(pattern, path, options = {}) {
-		return this.#ws.fs.grep(pattern, path, options);
+		return withSpan(this.#ws.observer, "workspace.fs.grep", {
+			"workspace.fs.path": path,
+			"workspace.fs.pattern": pattern
+		}, () => this.#ws.fs.grep(pattern, path, options), (span, outcome) => {
+			if (outcome.ok) span.setAttribute("workspace.fs.matches", outcome.value.length);
+		});
 	}
 	writeFile(path, content, options = {}) {
-		return this.#ws.fs.writeFile(path, content, options);
+		return withSpan(this.#ws.observer, "workspace.fs.writeFile", { "workspace.fs.path": path }, () => this.#ws.fs.writeFile(path, content, options));
 	}
 	mkdir(path, options = {}) {
-		return this.#ws.fs.mkdir(path, options);
+		return withSpan(this.#ws.observer, "workspace.fs.mkdir", {
+			"workspace.fs.path": path,
+			"workspace.fs.recursive": options.recursive
+		}, () => this.#ws.fs.mkdir(path, options));
 	}
 	rm(path, options = {}) {
-		return this.#ws.fs.rm(path, options);
+		return withSpan(this.#ws.observer, "workspace.fs.rm", {
+			"workspace.fs.path": path,
+			"workspace.fs.recursive": options.recursive,
+			"workspace.fs.force": options.force
+		}, () => this.#ws.fs.rm(path, options));
 	}
 };
 var WorkspaceExecHandleStub = class extends RpcTarget {
@@ -2320,10 +2406,19 @@ var WorkspaceShellStub = class extends RpcTarget {
 		untrackStub(this);
 	}
 	async exec(command, options = {}) {
-		return new WorkspaceExecHandleStub(options.encoding === "utf8" ? this.#ws.shell.exec(command, {
+		return new WorkspaceExecHandleStub(withSpan(this.#ws.observer, "workspace.shell.exec", {
+			"workspace.shell.cwd": options.cwd,
+			"workspace.shell.encoding": options.encoding
+		}, () => options.encoding === "utf8" ? this.#ws.shell.exec(command, {
 			cwd: options.cwd,
 			encoding: "utf8"
-		}).then((handle) => handle.result()) : this.#ws.shell.exec(command, { cwd: options.cwd }).then((handle) => handle.result()));
+		}).then((handle) => handle.result()) : this.#ws.shell.exec(command, { cwd: options.cwd }).then((handle) => handle.result()), (span, outcome) => {
+			if (!outcome.ok) return;
+			span.setAttribute("workspace.shell.exit_code", outcome.value.exitCode);
+			span.setAttribute("workspace.shell.pushed", outcome.value.pushed);
+			span.setAttribute("workspace.shell.pulled", outcome.value.pulled);
+			span.setAttribute("workspace.shell.skipped", outcome.value.skipped.length);
+		}));
 	}
 };
 var WorkspaceStub = class extends RpcTarget {
@@ -2736,6 +2831,7 @@ var Workspace = class {
 	#provider;
 	#backends;
 	#reconnect;
+	#observer;
 	#now;
 	#mounts;
 	#mountIndex;
@@ -2755,6 +2851,7 @@ var Workspace = class {
 			initialDelayMs: 0,
 			maxDelayMs: 0
 		};
+		this.#observer = options.observer ?? noopObserver;
 		this.#mounts = buildMountRegistry(options.mounts, {
 			sessionId: options.sessionId,
 			vfs: () => this.provider()
@@ -2774,6 +2871,9 @@ var Workspace = class {
 	get db() {
 		return this.#db;
 	}
+	get observer() {
+		return this.#observer;
+	}
 	get fs() {
 		return this.#fs;
 	}
@@ -2825,18 +2925,24 @@ var Workspace = class {
 		return new WorkspaceStub(this);
 	}
 	push() {
-		return this.#serialize(async () => {
+		return this.#serialize(() => withSpan(this.#observer, "workspace.sync.push", {}, async () => {
 			await this.ready();
 			if (!this.#handle) throw new Error("Workspace not connected");
 			return pushOnce(this.#db, this.#handle.rpc.sync);
-		});
+		}, (span, outcome) => {
+			if (outcome.ok) span.setAttribute("workspace.sync.pushed", outcome.value);
+		}));
 	}
 	pull() {
-		return this.#serialize(async () => {
+		return this.#serialize(() => withSpan(this.#observer, "workspace.sync.pull", {}, async () => {
 			await this.ready();
 			if (!this.#handle) throw new Error("Workspace not connected");
 			return pullOnce(this.#db, this.#handle.rpc.sync);
-		});
+		}, (span, outcome) => {
+			if (!outcome.ok) return;
+			span.setAttribute("workspace.sync.applied", outcome.value.applied);
+			span.setAttribute("workspace.sync.skipped", outcome.value.skipped.length);
+		}));
 	}
 	#serialize(fn) {
 		const run = this.#mutationTail.then(fn, fn);
@@ -2870,10 +2976,10 @@ var Workspace = class {
 	async #connectOnce() {
 		const errors = [];
 		for (const backend of this.#backends) try {
-			const handle = await backend.connect();
+			const handle = await withSpan(this.#observer, "workspace.connect", { "workspace.backend.id": backend.id }, () => backend.connect());
 			await reconcileWatermarks(this.#db, handle.rpc.sync);
 			this.#handle = handle;
-			this.#shell = new WorkspaceShell(handle.rpc.shell, this);
+			this.#shell = new WorkspaceShell(handle.rpc.shell, this, this.#observer);
 			if (handle.closed) handle.closed.catch(() => {}).then(() => {
 				if (this.#handle === handle) {
 					this.#handle = void 0;
@@ -2897,6 +3003,6 @@ function sleep(ms) {
 	return new Promise((resolve) => setTimeout(resolve, ms));
 }
 //#endregion
-export { CloudflareContainerBackend, R2Bucket, SQLiteWorkspaceProvider, TestBackend, Workspace, WorkspaceContainerAPI, WorkspaceExecHandleStub, WorkspaceFilesystemStub, WorkspaceProxy, WorkspaceShell, WorkspaceShellStub, WorkspaceStub, withWorkspaceContainer };
+export { CloudflareContainerBackend, R2Bucket, SQLiteWorkspaceProvider, TestBackend, Workspace, WorkspaceContainerAPI, WorkspaceExecHandleStub, WorkspaceFilesystemStub, WorkspaceProxy, WorkspaceShell, WorkspaceShellStub, WorkspaceStub, noopObserver, withWorkspaceContainer };
 
 //# sourceMappingURL=index.js.map