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

package/dist/observe/cloudflare.d.ts

@@ -0,0 +1,27 @@
+import { r as WorkspaceObserver } from "../shared-DYgflRlD.js";
+
+//#region src/observe/cloudflare.d.ts
+interface CloudflareObserverOptions {
+  /**
+   * The runtime's user-tracing handle. Pass `ctx.tracing` from inside a
+   * Worker or Durable Object, or `tracing` imported from
+   * `cloudflare:workers`. `undefined` is accepted because the runtime
+   * omits the property in environments without the user-tracing
+   * feature flag; the adapter then degrades to a pass-through.
+   */
+  tracing: Tracing | undefined;
+}
+/**
+ * Build a `WorkspaceObserver` backed by the Cloudflare runtime's built-in
+ * user tracing surface.
+ *
+ * When `tracing` is `undefined`, returns an observer that runs the
+ * callback directly with a span object whose `setAttribute` is a no-op.
+ * This lets the same wiring code work in environments without the
+ * user-tracing feature flag, without forcing callers to branch on a
+ * possibly-undefined `ctx.tracing`.
+ */
+declare function createCloudflareObserver(options: CloudflareObserverOptions): WorkspaceObserver;
+//#endregion
+export { CloudflareObserverOptions, createCloudflareObserver };
+//# sourceMappingURL=cloudflare.d.ts.map

package/dist/observe/cloudflare.js

@@ -0,0 +1,38 @@
+//#region src/observe/cloudflare.ts
+/**
+* Build a `WorkspaceObserver` backed by the Cloudflare runtime's built-in
+* user tracing surface.
+*
+* When `tracing` is `undefined`, returns an observer that runs the
+* callback directly with a span object whose `setAttribute` is a no-op.
+* This lets the same wiring code work in environments without the
+* user-tracing feature flag, without forcing callers to branch on a
+* possibly-undefined `ctx.tracing`.
+*/
+function createCloudflareObserver(options) {
+	const { tracing } = options;
+	if (!tracing) return passThroughObserver;
+	return { span(name, attributes, run) {
+		return tracing.enterSpan(name, (runtimeSpan) => {
+			applyAttributes(runtimeSpan, attributes);
+			return run({ setAttribute(key, value) {
+				if (value === void 0) return;
+				runtimeSpan.setAttribute(key, value);
+			} });
+		});
+	} };
+}
+function applyAttributes(runtimeSpan, attributes) {
+	for (const [key, value] of Object.entries(attributes)) {
+		if (value === void 0) continue;
+		runtimeSpan.setAttribute(key, value);
+	}
+}
+const passThroughSpan = { setAttribute() {} };
+const passThroughObserver = { span(_name, _attributes, run) {
+	return run(passThroughSpan);
+} };
+//#endregion
+export { createCloudflareObserver };
+
+//# sourceMappingURL=cloudflare.js.map

package/dist/observe/cloudflare.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloudflare.js","names":[],"sources":["../../src/observe/cloudflare.ts"],"sourcesContent":["// Cloudflare runtime adapter for the workspace observer hook.\n//\n// Wires `@cloudflare/workspace`'s span-shaped observer to the Cloudflare\n// runtime's built-in user tracing surface (`Tracing.enterSpan`). The\n// runtime owns the span lifecycle: it opens the span, propagates the\n// active context through `AsyncContextFrame` so nested spans become\n// children automatically, and ends the span when the callback's return\n// value (or promise) settles.\n//\n// Two ways to obtain a `Tracing` handle in user code:\n//\n//   import { tracing } from \"cloudflare:workers\";\n//\n//   const observer = createCloudflareObserver({ tracing });\n//\n// or, when an `ExecutionContext` is on hand:\n//\n//   const observer = createCloudflareObserver({ tracing: ctx.tracing });\n//\n// `ctx.tracing` is optional on the `ExecutionContext` type because the\n// runtime omits it in environments without the user-tracing feature\n// flag. The adapter accepts `Tracing | undefined`; when it is undefined\n// the observer is a pure pass-through.\n//\n// Why this adapter is so small\n// ----------------------------\n// The shape of `WorkspaceObserver.span(name, attributes, run)` is a\n// faithful subset of `tracing.enterSpan(name, callback)`. The only\n// real work the adapter does is forward seed attributes onto the\n// runtime span and hand a `setAttribute`-shaped facade to the workspace\n// callback. Errors propagate through `enterSpan` naturally; the\n// workspace's own `withSpan` helper records `error.name` /\n// `error.message` before re-throwing.\n//\n// Why we do not depend on `cloudflare:workers`\n// --------------------------------------------\n// The adapter takes the `Tracing` instance as an argument rather than\n// importing it directly. That keeps this file resolvable under the\n// node-based unit tests (where `cloudflare:workers` is not present),\n// and it keeps the workspace package free of an implicit dependency on\n// the runtime module specifier in tools that do not understand it.\n\nimport type { WorkspaceObserver, WorkspaceSpan } from \"../observe.js\";\n\nexport interface CloudflareObserverOptions {\n  /**\n   * The runtime's user-tracing handle. Pass `ctx.tracing` from inside a\n   * Worker or Durable Object, or `tracing` imported from\n   * `cloudflare:workers`. `undefined` is accepted because the runtime\n   * omits the property in environments without the user-tracing\n   * feature flag; the adapter then degrades to a pass-through.\n   */\n  tracing: Tracing | undefined;\n}\n\n/**\n * Build a `WorkspaceObserver` backed by the Cloudflare runtime's built-in\n * user tracing surface.\n *\n * When `tracing` is `undefined`, returns an observer that runs the\n * callback directly with a span object whose `setAttribute` is a no-op.\n * This lets the same wiring code work in environments without the\n * user-tracing feature flag, without forcing callers to branch on a\n * possibly-undefined `ctx.tracing`.\n */\nexport function createCloudflareObserver(options: CloudflareObserverOptions): WorkspaceObserver {\n  const { tracing } = options;\n  if (!tracing) return passThroughObserver;\n  return {\n    span(name, attributes, run) {\n      // The runtime requires the operation name to fit in 64 bytes.\n      // Names emitted by the workspace are well under that today\n      // (longest is `workspace.shell.exec.spawn` at 26 bytes), so no\n      // truncation is needed here; an over-length name is a workspace\n      // bug rather than a caller bug.\n      return tracing.enterSpan(name, (runtimeSpan) => {\n        applyAttributes(runtimeSpan, attributes);\n        // Wrap the runtime span in a `WorkspaceSpan` facade. The facade\n        // forwards `setAttribute` directly; `undefined` values are\n        // dropped so callers can pass optional fields without\n        // conditionals.\n        const span: WorkspaceSpan = {\n          setAttribute(key, value) {\n            if (value === undefined) return;\n            runtimeSpan.setAttribute(key, value);\n          },\n        };\n        return run(span);\n      });\n    },\n  };\n}\n\nfunction applyAttributes(\n  runtimeSpan: Span,\n  attributes: Readonly<Record<string, boolean | number | string | undefined>>,\n): void {\n  for (const [key, value] of Object.entries(attributes)) {\n    if (value === undefined) continue;\n    runtimeSpan.setAttribute(key, value);\n  }\n}\n\n// Used when the runtime does not expose `Tracing`. The callback runs\n// inline and the span facade is a no-op, matching the package's default\n// `noopObserver`. Duplicated here rather than re-exported to keep the\n// adapter file self-contained and avoid pulling the package entry into\n// the import graph of every adapter consumer.\nconst passThroughSpan: WorkspaceSpan = {\n  setAttribute() {\n    // intentionally empty\n  },\n};\n\nconst passThroughObserver: WorkspaceObserver = {\n  span(_name, _attributes, run) {\n    return run(passThroughSpan);\n  },\n};\n"],"mappings":";;;;;;;;;;;AAiEA,SAAgB,yBAAyB,SAAuD;CAC9F,MAAM,EAAE,YAAY;CACpB,IAAI,CAAC,SAAS,OAAO;CACrB,OAAO,EACL,KAAK,MAAM,YAAY,KAAK;EAM1B,OAAO,QAAQ,UAAU,OAAO,gBAAgB;GAC9C,gBAAgB,aAAa,UAAU;GAWvC,OAAO,IAAI,EALT,aAAa,KAAK,OAAO;IACvB,IAAI,UAAU,KAAA,GAAW;IACzB,YAAY,aAAa,KAAK,KAAK;GACrC,EAEY,CAAC;EACjB,CAAC;CACH,EACF;AACF;AAEA,SAAS,gBACP,aACA,YACM;CACN,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,UAAU,GAAG;EACrD,IAAI,UAAU,KAAA,GAAW;EACzB,YAAY,aAAa,KAAK,KAAK;CACrC;AACF;AAOA,MAAM,kBAAiC,EACrC,eAAe,CAEf,EACF;AAEA,MAAM,sBAAyC,EAC7C,KAAK,OAAO,aAAa,KAAK;CAC5B,OAAO,IAAI,eAAe;AAC5B,EACF"}

package/dist/shared-DYgflRlD.d.ts

@@ -0,0 +1,63 @@
+//#region src/observe.d.ts
+/**
+ * Attribute values accepted by `WorkspaceSpan.setAttribute` and the
+ * initial `attributes` map passed to `Observer.span`.
+ *
+ * Restricted to scalar types so the same shape works against the
+ * Cloudflare runtime's built-in `Span.setAttribute` and against
+ * `@opentelemetry/api` without per-adapter coercion.
+ */
+type WorkspaceAttributeValue = boolean | number | string;
+/**
+ * Initial attributes passed when a span is started. `undefined` values
+ * are dropped — adapters do not forward them to the underlying span.
+ * This matches the Cloudflare runtime, where `setAttribute(key,
+ * undefined)` is a no-op.
+ */
+type WorkspaceAttributes = Readonly<Record<string, WorkspaceAttributeValue | undefined>>;
+/**
+ * Handle passed to the callback inside `Observer.span`. The only
+ * mutating method is `setAttribute`, matching the Cloudflare
+ * `ctx.tracing` `Span` surface. Adapters that target a richer system
+ * may expose more on their own internal types, but the workspace
+ * itself only ever calls these methods.
+ */
+interface WorkspaceSpan {
+  /**
+   * Sets a single attribute on the span. Passing `undefined` is a
+   * no-op so callers can forward optional values directly.
+   */
+  setAttribute(key: string, value: WorkspaceAttributeValue | undefined): void;
+}
+/**
+ * Observer hook. A single `span` method that wraps a piece of work —
+ * the adapter starts a span, runs the callback, and ends the span when
+ * the callback's return value (or its returned promise) settles.
+ *
+ * The default observer is a no-op (see `noopObserver`); the workspace
+ * uses it when the caller does not pass one. Adapters live in separate
+ * subpaths so callers do not pay for `@opentelemetry/api` or
+ * `cloudflare:workers` just to import the workspace.
+ */
+interface WorkspaceObserver {
+  /**
+   * Wraps `run` in a span named `name`, seeded with `attributes`. The
+   * callback receives a `WorkspaceSpan` it can use to attach further
+   * attributes once the work has produced values worth recording (byte
+   * counts, exit codes, applied / skipped counts).
+   *
+   * Implementations must run `run` synchronously and return its result
+   * (or its promise) unchanged so the wrapping is invisible to the
+   * caller. Errors thrown by `run` must propagate.
+   */
+  span<T>(name: string, attributes: WorkspaceAttributes, run: (span: WorkspaceSpan) => Promise<T>): Promise<T>;
+}
+/**
+ * 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.
+ */
+declare const noopObserver: WorkspaceObserver;
+//#endregion
+export { noopObserver as a, WorkspaceSpan as i, WorkspaceAttributes as n, WorkspaceObserver as r, WorkspaceAttributeValue as t };
+//# sourceMappingURL=shared-DYgflRlD.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cloudflare/workspace",
-  "version": "0.0.0-alpha.2",
+  "version": "0.0.0-alpha.4",
   "description": "Cloudflare Workspace — a SQLite-backed virtual filesystem with sync to a container-side daemon (wsd).",
   "license": "MIT",
   "repository": {
@@ -18,6 +18,10 @@
     "./git": {
       "types": "./dist/git.d.ts",
       "import": "./dist/git.js"
+    },
+    "./observe/cloudflare": {
+      "types": "./dist/observe/cloudflare.d.ts",
+      "import": "./dist/observe/cloudflare.js"
     }
   },
   "main": "./dist/index.js",