@inferencebureau/apps-sdk 0.10.0 → 0.11.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/dist/runtime.d.ts CHANGED
@@ -26,7 +26,12 @@ export interface ActionRequest {
26
26
  /** The run's event in Logs: the action's `ai` calls sit under it. */
27
27
  event?: string;
28
28
  }
29
- export type ActionResponse = {
29
+ /** The phase's timed calls, for its trace in Logs, when the run was traced (the /_ib/actions route traces every run). */
30
+ interface Traced {
31
+ spans?: Span[];
32
+ droppedSpans?: number;
33
+ }
34
+ export type ActionResponse = ({
30
35
  ok: true;
31
36
  write: {
32
37
  op: "save";
@@ -37,14 +42,31 @@ export type ActionResponse = {
37
42
  writes?: StagedWrite[];
38
43
  result?: unknown;
39
44
  logs: LogLine[];
40
- } | {
45
+ } & Traced) | ({
41
46
  ok: false;
42
47
  error: {
43
48
  message: string;
44
49
  stack?: string;
45
50
  };
46
51
  logs: LogLine[];
47
- };
52
+ } & Traced);
53
+ /**
54
+ * One call the action made while it ran, for its trace in Logs: what it was, when it started (ms into the phase) and
55
+ * how long it took to answer. Calls to Inference Bureau are named by what they did (a record read, a Shopify query);
56
+ * anything else is an outbound `fetch`, named by its method, host and path (never its query string).
57
+ */
58
+ export interface Span {
59
+ kind: "read" | "write" | "action" | "job" | "shopify" | "ai" | "api" | "fetch";
60
+ name: string;
61
+ at: number;
62
+ ms: number;
63
+ status?: number;
64
+ error?: true;
65
+ }
66
+ /** The most spans a phase reports; past it they're counted, not kept. */
67
+ export declare const MAX_SPANS = 200;
68
+ /** What a call was, from where it went: the records API, Shopify, jobs and models by their route, anything else as fetch. */
69
+ export declare function spanOf(input: string | URL | Request, init?: RequestInit): Pick<Span, "kind" | "name">;
48
70
  /** The signature Inference Bureau sends: HMAC-SHA256 of `<timestamp>.<body>` with the environment's token, hex. */
49
71
  export declare function sign(token: string, timestamp: string, body: string): Promise<string>;
50
72
  /**
@@ -59,9 +81,11 @@ export declare function runAction(req: ActionRequest, registry: ActionRegistry,
59
81
  ai?: AiClient;
60
82
  echo?: boolean;
61
83
  signal?: AbortSignal;
84
+ trace?: boolean;
62
85
  }): Promise<ActionResponse>;
63
86
  /** The `/_ib/actions` route: a signed request from Inference Bureau, or 404 for anyone else. */
64
87
  export declare function handleAction(request: Request, registry: ActionRegistry, o?: {
65
88
  token?: string;
66
89
  now?: () => number;
67
90
  }): Promise<Response>;
91
+ export {};
package/dist/runtime.js CHANGED
@@ -6,6 +6,121 @@
6
6
  * the saved record.
7
7
  */
8
8
  import { createAiClient, createClient, createShopifyClient, newRecordId, pendingWrite, stagedWrites, trackRecord } from "./index.js";
9
+ /** The most spans a phase reports; past it they're counted, not kept. */
10
+ export const MAX_SPANS = 200;
11
+ const clock = () => globalThis.performance?.now?.() ?? Date.now();
12
+ const IB_PATH = /\/v1\/apps\/[^/]*\/environments\/[^/]*\/(.*)$/;
13
+ function bodyJson(init) {
14
+ if (typeof init?.body !== "string")
15
+ return {};
16
+ try {
17
+ const v = JSON.parse(init.body);
18
+ return v && typeof v === "object" ? v : {};
19
+ }
20
+ catch {
21
+ return {};
22
+ }
23
+ }
24
+ /** What a call was, from where it went: the records API, Shopify, jobs and models by their route, anything else as fetch. */
25
+ export function spanOf(input, init) {
26
+ const url = new URL(typeof input === "string" ? input : input instanceof URL ? input.href : input.url);
27
+ const method = (init?.method ?? (typeof input === "object" && "method" in input ? input.method : "GET")).toUpperCase();
28
+ const m = IB_PATH.exec(url.pathname);
29
+ if (!m)
30
+ return { kind: "fetch", name: `${method} ${url.host}${url.pathname}` };
31
+ const [a, b, c, d] = m[1].split("/").map((p) => { try {
32
+ return decodeURIComponent(p);
33
+ }
34
+ catch {
35
+ return p;
36
+ } });
37
+ if (a === "models" && b) {
38
+ if (c === "records" && (d === "query" || method === "GET"))
39
+ return { kind: "read", name: `${d === "query" ? "findMany" : "findOne"} ${b}` };
40
+ if (c === "records")
41
+ return { kind: "write", name: `${method === "POST" ? "create" : method === "DELETE" ? "delete" : "update"} ${b}` };
42
+ if (c === "actions" && d)
43
+ return { kind: "action", name: `${b}.${d}` };
44
+ if (c === "uploads")
45
+ return { kind: "write", name: `upload ${b}` };
46
+ }
47
+ if (a === "actions" && b)
48
+ return { kind: "action", name: b };
49
+ if (a === "jobs" && method === "POST" && !b)
50
+ return { kind: "job", name: `enqueue ${String(bodyJson(init).action ?? "")}`.trim() };
51
+ if (a === "shopify") {
52
+ if (b === "graphql") {
53
+ const op = /\b(query|mutation)\s+([A-Za-z_]\w*)/.exec(String(bodyJson(init).query ?? ""));
54
+ return { kind: "shopify", name: op ? `${op[1]} ${op[2]}` : "graphql" };
55
+ }
56
+ return { kind: "shopify", name: [b, c].filter(Boolean).join(" ") || "shopify" };
57
+ }
58
+ if (a === "ai") {
59
+ const model = bodyJson(init).model;
60
+ return { kind: "ai", name: `${b === "embeddings" ? "embed" : b === "chat" ? "chat" : b ?? "ai"}${typeof model === "string" ? ` ${model}` : ""}` };
61
+ }
62
+ return { kind: "api", name: `${method} /${m[1]}` };
63
+ }
64
+ function tracedFetch(trace, base) {
65
+ return (async (input, init) => {
66
+ const at = clock();
67
+ let status;
68
+ let failed = false;
69
+ try {
70
+ const res = await base(input, init);
71
+ status = res.status;
72
+ failed = !res.ok;
73
+ return res;
74
+ }
75
+ catch (e) {
76
+ failed = true;
77
+ throw e;
78
+ }
79
+ finally {
80
+ if (trace.spans.length >= MAX_SPANS)
81
+ trace.dropped++;
82
+ else {
83
+ let what;
84
+ try {
85
+ what = spanOf(input, init);
86
+ }
87
+ catch {
88
+ what = { kind: "fetch", name: "fetch" };
89
+ }
90
+ trace.spans.push({ ...what, at: Math.round(at - trace.t0), ms: Math.round(clock() - at), ...(status !== undefined ? { status } : {}), ...(failed ? { error: true } : {}) });
91
+ }
92
+ }
93
+ });
94
+ }
95
+ let storage;
96
+ /** The store the action's own clients call under: they time their calls themselves, so the global fetch doesn't again. */
97
+ const PASS = Symbol("untraced");
98
+ /**
99
+ * The fetches the action's own code makes, timed as its run's: where the runtime has AsyncLocalStorage (Node; Workers
100
+ * with nodejs_compat), the global fetch is wrapped once, and a call made inside a run is a span of that run. Calls
101
+ * outside a run pass straight through. Elsewhere only the action's `api`, `shopify` and `ai` calls are timed.
102
+ */
103
+ function runStorage() {
104
+ if (storage !== undefined)
105
+ return storage;
106
+ const g = globalThis;
107
+ let Als;
108
+ try {
109
+ Als = g.AsyncLocalStorage ?? g.process?.getBuiltinModule?.("node:async_hooks")?.AsyncLocalStorage;
110
+ }
111
+ catch {
112
+ Als = undefined;
113
+ }
114
+ if (!Als || typeof globalThis.fetch !== "function")
115
+ return (storage = null);
116
+ const s = new Als();
117
+ const original = globalThis.fetch;
118
+ globalThis.fetch = ((input, init) => {
119
+ const t = s.getStore();
120
+ return t && t !== PASS ? tracedFetch(t, original)(input, init) : original(input, init);
121
+ });
122
+ return (storage = s);
123
+ }
9
124
  const SKEW_MS = 5 * 60_000;
10
125
  const encoder = new TextEncoder();
11
126
  const envVar = (name) => globalThis.process?.env?.[name];
@@ -78,6 +193,14 @@ function stagingApi(api, handed) {
78
193
  */
79
194
  export async function runAction(req, registry, o = {}) {
80
195
  const logs = [];
196
+ // A traced run times the calls its clients make, and with AsyncLocalStorage its own code's fetches too.
197
+ const trace = o.trace ? { t0: clock(), spans: [], dropped: 0 } : null;
198
+ const store = trace ? runStorage() : null;
199
+ // The clients' calls go through whatever the global fetch is when they're made, outside the run's own timing.
200
+ const f = trace ? tracedFetch(trace, (input, init) => (store ? store.run(PASS, () => globalThis.fetch(input, init)) : globalThis.fetch(input, init))) : null;
201
+ const withFetch = f ? { fetch: f } : {};
202
+ const traced = () => (trace ? { spans: trace.spans, ...(trace.dropped ? { droppedSpans: trace.dropped } : {}) } : {});
203
+ const inRun = (fn) => (store && trace ? store.run(trace, fn) : fn());
81
204
  try {
82
205
  const key = req.model ? `${req.model}/${req.action}` : `$global/${req.action}`;
83
206
  const load = registry[key];
@@ -89,28 +212,28 @@ export async function runAction(req, registry, o = {}) {
89
212
  const logger = collector(logs, o.echo ?? true);
90
213
  const signal = o.signal ?? new AbortController().signal;
91
214
  const ctx = {
92
- params: req.params ?? {}, record, api: stagingApi(scopedApi(o.api ?? createClient(o.token ? { token: o.token } : {}), req.shop), handed), logger,
215
+ params: req.params ?? {}, record, api: stagingApi(scopedApi(o.api ?? createClient({ ...(o.token ? { token: o.token } : {}), ...withFetch }), req.shop), handed), logger,
93
216
  model: req.model, action: req.action, environment: req.environment, signal,
94
- caller: req.caller ?? null, shop: req.shop ?? null, shopify: req.shop ? (o.shopify?.(req.shop) ?? createShopifyClient(req.shop, { ...(o.token ? { token: o.token } : {}), ...(req.background ? { priority: "background" } : {}) })) : null,
95
- ai: o.ai ?? createAiClient({ ...(o.token ? { token: o.token } : {}), ...(req.event ? { event: req.event } : {}), signal }),
217
+ caller: req.caller ?? null, shop: req.shop ?? null, shopify: req.shop ? (o.shopify?.(req.shop) ?? createShopifyClient(req.shop, { ...(o.token ? { token: o.token } : {}), ...withFetch, ...(req.background ? { priority: "background" } : {}) })) : null,
218
+ ai: o.ai ?? createAiClient({ ...(o.token ? { token: o.token } : {}), ...withFetch, ...(req.event ? { event: req.event } : {}), signal }),
96
219
  };
97
220
  if (req.phase === "onSuccess") {
98
- await mod.onSuccess?.(ctx);
221
+ await inRun(async () => mod.onSuccess?.(ctx));
99
222
  if (stagedWrites(handed).length || (record && pendingWrite(record, false))) {
100
223
  logger.warn("save() and deleteRecord() write nothing in onSuccess: the run's changes have already committed. Use api.<model>.update() here, or save in run.");
101
224
  }
102
- return { ok: true, write: null, logs };
225
+ return { ok: true, write: null, logs, ...traced() };
103
226
  }
104
227
  if (typeof mod.run !== "function")
105
228
  throw new Error(`${key} doesn't export a run function.`);
106
- const result = await mod.run(ctx);
229
+ const result = await inRun(async () => mod.run(ctx));
107
230
  const write = record ? pendingWrite(record, req.isNew) : null;
108
231
  const writes = stagedWrites(handed);
109
- return { ok: true, write, ...(writes.length ? { writes } : {}), ...(mod.options?.returnType && result !== undefined ? { result } : {}), logs };
232
+ return { ok: true, write, ...(writes.length ? { writes } : {}), ...(mod.options?.returnType && result !== undefined ? { result } : {}), logs, ...traced() };
110
233
  }
111
234
  catch (e) {
112
235
  const err = e instanceof Error ? e : new Error(String(e));
113
- return { ok: false, error: { message: err.message, ...(err.stack ? { stack: err.stack.split("\n").slice(0, 8).join("\n") } : {}) }, logs };
236
+ return { ok: false, error: { message: err.message, ...(err.stack ? { stack: err.stack.split("\n").slice(0, 8).join("\n") } : {}) }, logs, ...traced() };
114
237
  }
115
238
  }
116
239
  /** The `/_ib/actions` route: a signed request from Inference Bureau, or 404 for anyone else. */
@@ -130,6 +253,6 @@ export async function handleAction(request, registry, o = {}) {
130
253
  return new Response("Bad request", { status: 400 });
131
254
  }
132
255
  // The request is aborted when Inference Bureau stops waiting: the job was canceled, or the time ran out.
133
- const res = await runAction(req, registry, { token, signal: request.signal });
256
+ const res = await runAction(req, registry, { token, signal: request.signal, trace: true });
134
257
  return new Response(JSON.stringify(res), { status: 200, headers: { "content-type": "application/json", "cache-control": "no-store" } });
135
258
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@inferencebureau/apps-sdk",
3
- "version": "0.10.0",
3
+ "version": "0.11.0",
4
4
  "description": "The SDK an Inference Bureau app's code imports: action helpers, metadata types, the records API client and a test harness for its actions.",
5
5
  "license": "UNLICENSED",
6
6
  "keywords": [