@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 +27 -3
- package/dist/runtime.js +132 -9
- package/package.json +1 -1
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
|
-
|
|
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.
|
|
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": [
|