@voltro/plugin-webhooks 0.85.0 → 0.86.0

package/THIRD-PARTY-NOTICES.md

@@ -1,11 +1,11 @@
 # Third-Party Notices — @voltro/plugin-webhooks
 
-This package depends on the open-source software listed below. Each is the
+This package uses the open-source software listed below. Each is the
 property of its respective copyright holders and is used under the terms of
 its license. This file is provided for attribution; it grants no rights in
 @voltro/plugin-webhooks itself, which is proprietary (see LICENSE).
 
-Generated from the resolved runtime dependency closure (42 packages).
+Generated from the resolved runtime dependency closure (41 packages).
 
 ---
 
@@ -3636,34 +3636,6 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 ```
 
-## layerr@3.0.0
-
-License: MIT
-
-```
-MIT License
-
-Copyright (c) 2020 Perry Mitchell
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
-```
-
 ## lib0@0.2.117
 
 License: MIT
@@ -4013,14 +3985,14 @@ Apache License
    limitations under the License.
 ```
 
-## ulidx@2.4.1
+## ulid@3.0.2
 
 License: MIT
 
 ```
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2021 Perry Mitchell
+Copyright (c) 2017 Alizain Feerasta
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/dist/autoDisable.js

@@ -0,0 +1,41 @@
+import { and as e, eq as t } from "@voltro/database";
+//#region src/autoDisable.ts
+var n = "_voltro_webhook_targets", r = 32, i = async (e, n) => (await e.query({
+	table: "_voltro_webhook_targets",
+	predicate: t("id", n),
+	order: [],
+	take: 1,
+	skip: void 0,
+	projection: void 0
+}))[0] ?? null, a = async (n, a, o, s, c = /* @__PURE__ */ new Date(), l = !1) => {
+	for (let u = 0; u < r; u++) {
+		u > 0 && await new Promise((e) => setTimeout(e, u));
+		let r = await i(n, a);
+		if (r === null) return {
+			consecutiveFailures: 0,
+			autoDisabled: !1
+		};
+		let d = r.consecutiveFailures ?? 0;
+		if (o) {
+			if (d === 0 || await n.updateMany("_voltro_webhook_targets", {
+				consecutiveFailures: 0,
+				updatedAt: c
+			}, { where: e(t("id", a), t("consecutiveFailures", d)) }) === 1) return {
+				consecutiveFailures: 0,
+				autoDisabled: !1
+			};
+			continue;
+		}
+		let f = d + 1, p = r.autoDisableAfter, m = r.active && (l || typeof p == "number" && p > 0 && f >= p), h = {
+			consecutiveFailures: f,
+			updatedAt: c
+		};
+		if (m && (h.active = !1, h.autoDisabledAt = c, h.autoDisableReason = s.slice(0, 500)), await n.updateMany("_voltro_webhook_targets", h, { where: e(t("id", a), t("consecutiveFailures", d)) }) === 1) return {
+			consecutiveFailures: f,
+			autoDisabled: m
+		};
+	}
+	throw Error(`webhook auto-disable: streak CAS contention on target ${a} exceeded ${r} attempts`);
+};
+//#endregion
+export { n as TARGETS_TABLE, a as recordDeliveryOutcome };

package/dist/deferredEmit.js

@@ -0,0 +1,17 @@
+import { defineOutboxHandler as e } from "@voltro/runtime";
+//#region src/deferredEmit.ts
+var t = "voltro.webhook.emit", n = (e) => typeof e.event == "string", r = (r) => e({
+	effect: t,
+	maxAttempts: 1,
+	handler: async ({ payload: e, outboxId: i }) => {
+		if (!n(e)) throw Error(`${t}: row payload has no \`event\` name — cannot resolve a descriptor. Got keys: ${Object.keys(e).join(", ") || "(none)"}`);
+		let a = r();
+		if (a === void 0) throw Error(`${t}: the outgoing-webhooks service is not available in this process. An emit was enqueued by a build that had the plugin registered; this one does not.`);
+		await a.emit(e.event, e.payload, {
+			tenantId: e.tenantId,
+			eventId: i
+		});
+	}
+});
+//#endregion
+export { t as WEBHOOK_EMIT_EFFECT, r as makeDeferredEmitHandler };

package/dist/deliverWorkflow.js

@@ -0,0 +1,336 @@
+import { signRequest as e } from "./signing.js";
+import { nextRetry as t } from "./retry.js";
+import { WebhookPayloadUnrepresentable as n } from "./errors.js";
+import { acquireRateSlots as r } from "./rateLimit.js";
+import { encodePayload as i } from "./encode.js";
+import { recordDeliveryOutcome as a } from "./autoDisable.js";
+import { Effect as o, Schema as s } from "effect";
+import { eq as c } from "@voltro/database";
+import { assertPublicUrl as l } from "@voltro/integration-http";
+import { createLogger as u } from "@voltro/logger";
+import { Activity as d, DurableClock as f, Workflow as p } from "effect/workflow";
+//#region src/deliverWorkflow.ts
+var m = s.Struct({
+	status: s.Number,
+	body: s.String,
+	latencyMs: s.Number,
+	retryAfterSec: s.Union([s.Number, s.Undefined]),
+	transportError: s.Union([s.String, s.Undefined]),
+	encodeError: s.Union([s.String, s.Undefined])
+}), h = s.Struct({
+	outcome: s.Literals([
+		"succeeded",
+		"failed",
+		"retry"
+	]),
+	delayMs: s.Union([s.Number, s.Undefined]),
+	reason: s.Union([s.String, s.Undefined]),
+	autoDisabled: s.Union([s.Boolean, s.Undefined]),
+	consecutiveFailures: s.Union([s.Number, s.Undefined])
+}), g = s.Struct({
+	acquired: s.Boolean,
+	retryInMs: s.Number
+}), _ = {
+	deliveryId: s.String,
+	targetId: s.String,
+	event: s.String,
+	eventId: s.String,
+	payloadJson: s.String,
+	attemptEpoch: s.optional(s.Number)
+}, v = p.make("voltro.deliverWebhook", {
+	payload: _,
+	success: s.Struct({
+		finalStatus: s.Literals([
+			"succeeded",
+			"failed",
+			"deferred"
+		]),
+		attempts: s.Number
+	}),
+	idempotencyKey: ({ deliveryId: e, attemptEpoch: t }) => `voltro.deliverWebhook:${e}:${t ?? 0}`
+}), y = 3e4, b = (e, t) => {
+	if (e !== void 0) return e;
+	let n = Number(t.VOLTRO_WEBHOOK_TIMEOUT_MS);
+	return Number.isFinite(n) && n > 0 ? n : y;
+}, x = (p, _ = {}) => (v, y) => {
+	let { deliveryId: x, targetId: S, event: C, eventId: w, payloadJson: T } = v, E = u({ scope: `webhook:${x}` });
+	return o.gen(function* () {
+		let u = yield* d.make({
+			name: "fetch-target",
+			success: s.Union([s.Null, s.Struct({
+				id: s.String,
+				event: s.String,
+				url: s.String,
+				secret: s.String,
+				signing: s.Any,
+				retry: s.Any,
+				headers: s.Union([s.Record(s.String, s.String), s.Null]),
+				rateLimitPerMinute: s.Union([s.Number, s.Null]),
+				active: s.Boolean,
+				format: s.Literals([
+					"json",
+					"form",
+					"xml"
+				]),
+				tenantId: s.Union([s.String, s.Null])
+			})]),
+			execute: o.tryPromise({
+				try: async () => (await p.store.query({
+					table: "_voltro_webhook_targets",
+					predicate: c("id", S),
+					order: [{
+						column: "createdAt",
+						direction: "asc"
+					}],
+					take: 1,
+					skip: void 0,
+					projection: void 0
+				}))[0] ?? null,
+				catch: (e) => (E.debug("fetch-target raw error", {
+					targetId: S,
+					event: C,
+					cause: String(e)
+				}), /* @__PURE__ */ Error(`fetch-target failed: ${e.message}`))
+			}).pipe(o.orDie)
+		});
+		if (u === null) return {
+			finalStatus: "failed",
+			attempts: 0
+		};
+		let v = async (e, t, n) => {
+			await p.store.update("_voltro_webhook_deliveries", e, {
+				...n,
+				updatedAt: /* @__PURE__ */ new Date()
+			}) === null && await p.store.insert("_voltro_webhook_deliveries", {
+				id: e,
+				deliveryId: x,
+				targetId: S,
+				tenantId: u.tenantId ?? null,
+				event: C,
+				eventId: w,
+				attempt: t,
+				payload: T,
+				scheduledAt: /* @__PURE__ */ new Date(),
+				createdAt: /* @__PURE__ */ new Date(),
+				updatedAt: /* @__PURE__ */ new Date(),
+				...n
+			});
+		};
+		if (u.active !== !0) return yield* d.make({
+			name: "record-paused-pending",
+			success: s.Void,
+			execute: o.tryPromise({
+				try: () => v(`${x}:1`, 1, { status: "pending" }),
+				catch: (e) => /* @__PURE__ */ Error(`record-paused-pending failed: ${e.message}`)
+			}).pipe(o.orDie)
+		}), {
+			finalStatus: "deferred",
+			attempts: 0
+		};
+		let y = (e) => typeof e == "string" ? JSON.parse(e) : e, D = y(u.retry), O = y(u.signing), k = u.headers === null ? null : y(u.headers), A = _.rateWindowMs ?? 6e4, j = b(_.timeoutMs, process.env), M = _.events?.find((e) => e.id === C)?.globalRateLimit, N = [...typeof u.rateLimitPerMinute == "number" && u.rateLimitPerMinute > 0 ? [{
+			key: `target:${u.id}`,
+			limit: u.rateLimitPerMinute
+		}] : [], ...M !== void 0 && M.perMinute > 0 ? [{
+			key: `event:${C}`,
+			limit: M.perMinute
+		}] : []];
+		for (let c = 1; c <= D.maxAttempts; c++) {
+			let _ = `${x}:${c}`;
+			if (N.length > 0) for (let e = 0;; e++) {
+				let t = yield* d.make({
+					name: `rate-acquire-${c}-${e}`,
+					success: g,
+					execute: o.tryPromise({
+						try: () => r(p.store, N, Date.now(), A),
+						catch: (e) => (E.debug("rate-acquire raw error", {
+							targetId: S,
+							event: C,
+							attempt: c,
+							cause: String(e)
+						}), /* @__PURE__ */ Error(`rate-acquire failed: ${e.message}`))
+					}).pipe(o.orDie)
+				});
+				if (t.acquired) break;
+				yield* d.make({
+					name: `record-rate-deferral-${c}-${e}`,
+					success: s.Void,
+					execute: o.tryPromise({
+						try: () => v(_, c, {
+							status: "pending",
+							nextAttemptAt: new Date(Date.now() + t.retryInMs)
+						}),
+						catch: (e) => /* @__PURE__ */ Error(`record-rate-deferral failed: ${e.message}`)
+					}).pipe(o.orDie)
+				}), yield* f.sleep({
+					name: `rate-window-sleep-${c}-${e}`,
+					duration: `${t.retryInMs} millis`
+				});
+			}
+			yield* d.make({
+				name: `record-attempt-start-${c}`,
+				success: s.Void,
+				execute: o.tryPromise({
+					try: () => v(_, c, {
+						status: "inFlight",
+						nextAttemptAt: null,
+						scheduledAt: /* @__PURE__ */ new Date()
+					}),
+					catch: (e) => /* @__PURE__ */ Error(`record-attempt-start failed: ${e.message}`)
+				}).pipe(o.orDie)
+			});
+			let y = yield* d.make({
+				name: `sign-and-post-${c}`,
+				success: m,
+				execute: o.promise(async () => {
+					let t = Date.now(), r;
+					try {
+						r = i(u.format, T);
+					} catch (e) {
+						if (e instanceof n) return {
+							status: 0,
+							body: "",
+							latencyMs: Date.now() - t,
+							retryAfterSec: void 0,
+							transportError: void 0,
+							encodeError: e.reason
+						};
+						throw e;
+					}
+					let a = Buffer.from(r.bytes), { headers: o } = e(O, {
+						rawBody: a,
+						secret: u.secret,
+						messageId: x
+					});
+					process.env.NODE_ENV === "production" && l(u.url);
+					try {
+						let e = await fetch(u.url, {
+							method: "POST",
+							headers: {
+								"content-type": r.contentType,
+								...o,
+								"x-voltro-event": C,
+								"x-voltro-event-id": w,
+								"x-voltro-delivery-id": x,
+								"x-voltro-attempt": String(c),
+								"idempotency-key": x,
+								...k ?? {}
+							},
+							body: a,
+							redirect: "manual",
+							signal: AbortSignal.timeout(j)
+						}), n = (await e.text()).slice(0, 8192), i = e.headers.get("retry-after");
+						return {
+							status: e.status,
+							body: n,
+							latencyMs: Date.now() - t,
+							retryAfterSec: i !== null && /^\d+$/.test(i) ? Number(i) : void 0,
+							transportError: void 0,
+							encodeError: void 0
+						};
+					} catch (e) {
+						return {
+							status: 0,
+							body: "",
+							latencyMs: Date.now() - t,
+							retryAfterSec: void 0,
+							transportError: e.message,
+							encodeError: void 0
+						};
+					}
+				})
+			}), b = yield* d.make({
+				name: `classify-and-record-${c}`,
+				success: h,
+				execute: o.tryPromise({
+					try: async () => {
+						let e = y.status >= 200 && y.status < 300, n = y.transportError !== void 0, r = y.encodeError !== void 0, i = y.status === 410, o = (e, t) => a(p.store, S, e, t, /* @__PURE__ */ new Date(), !e && i);
+						if (e) {
+							await p.store.update("_voltro_webhook_deliveries", _, {
+								status: "succeeded",
+								responseStatus: y.status,
+								responseBody: y.body,
+								latencyMs: y.latencyMs,
+								updatedAt: /* @__PURE__ */ new Date()
+							});
+							let e = await o(!0, "");
+							return {
+								outcome: "succeeded",
+								delayMs: void 0,
+								reason: void 0,
+								autoDisabled: e.autoDisabled,
+								consecutiveFailures: e.consecutiveFailures
+							};
+						}
+						let s = r ? null : t(D, c, {
+							...n ? {} : { status: y.status },
+							...y.retryAfterSec === void 0 ? {} : { retryAfterSeconds: y.retryAfterSec }
+						});
+						if (s === null) {
+							let e = r ? `encode (${u.format}): ${y.encodeError}` : n ? `transport: ${y.transportError}` : `http ${y.status}: ${y.body.slice(0, 200)}`;
+							await p.store.update("_voltro_webhook_deliveries", _, {
+								status: "failed",
+								responseStatus: n || r ? null : y.status,
+								responseBody: n || r ? null : y.body,
+								errorMessage: r ? e : y.transportError ?? null,
+								latencyMs: y.latencyMs,
+								updatedAt: /* @__PURE__ */ new Date()
+							});
+							let t = await o(!1, e);
+							return {
+								outcome: "failed",
+								delayMs: void 0,
+								reason: e,
+								autoDisabled: t.autoDisabled,
+								consecutiveFailures: t.consecutiveFailures
+							};
+						}
+						return await p.store.update("_voltro_webhook_deliveries", _, {
+							status: "retryScheduled",
+							responseStatus: n ? null : y.status,
+							responseBody: n ? null : y.body,
+							errorMessage: y.transportError ?? null,
+							latencyMs: y.latencyMs,
+							nextAttemptAt: new Date(Date.now() + s.delayMs),
+							updatedAt: /* @__PURE__ */ new Date()
+						}), {
+							outcome: "retry",
+							delayMs: s.delayMs,
+							reason: void 0,
+							autoDisabled: void 0,
+							consecutiveFailures: void 0
+						};
+					},
+					catch: (e) => (E.debug("classify-and-record raw error", {
+						targetId: S,
+						event: C,
+						attempt: c,
+						cause: String(e)
+					}), /* @__PURE__ */ Error(`classify-and-record failed: ${e.message}`))
+				}).pipe(o.orDie)
+			});
+			if (b.autoDisabled === !0 && E.warn("target auto-disabled after consecutive failures", {
+				targetId: S,
+				event: C,
+				consecutiveFailures: b.consecutiveFailures ?? null,
+				reason: b.reason ?? null
+			}), b.outcome === "succeeded") return {
+				finalStatus: "succeeded",
+				attempts: c
+			};
+			if (b.outcome === "failed") return {
+				finalStatus: "failed",
+				attempts: c
+			};
+			b.delayMs !== void 0 && (yield* f.sleep({
+				name: `retry-sleep-${c}`,
+				duration: `${b.delayMs} millis`
+			}));
+		}
+		return {
+			finalStatus: "failed",
+			attempts: D.maxAttempts
+		};
+	});
+};
+//#endregion
+export { y as DEFAULT_WEBHOOK_TIMEOUT_MS, x as buildDeliverWebhookExecute, v as deliverWebhookWorkflow };

package/dist/dsl.js

@@ -0,0 +1,14 @@
+//#region src/dsl.ts
+var e = (e) => ({
+	_tag: "incomingWebhook",
+	...e
+}), t = (e) => ({
+	_tag: "webhookProvider",
+	...e
+}), n = (e) => {
+	if (typeof e != "object" || !e) return !1;
+	let t = e._tag;
+	return t === "outgoingEvent" || t === "incomingWebhook" || t === "webhookProvider";
+};
+//#endregion
+export { e as defineIncomingWebhook, t as defineWebhookProvider, n as isWebhookDescriptor };

package/dist/encode.js

@@ -0,0 +1,53 @@
+import { WebhookPayloadUnrepresentable as e } from "./errors.js";
+//#region src/encode.ts
+var t = (t, r) => {
+	if (t === "json") return {
+		contentType: "application/json",
+		bytes: Buffer.from(r, "utf8")
+	};
+	let i;
+	try {
+		i = JSON.parse(r);
+	} catch (n) {
+		throw new e({
+			format: t,
+			reason: `payload is not valid JSON: ${n.message}`
+		});
+	}
+	return t === "form" ? {
+		contentType: "application/x-www-form-urlencoded",
+		bytes: Buffer.from(n(i), "utf8")
+	} : {
+		contentType: "application/xml",
+		bytes: Buffer.from(a(i), "utf8")
+	};
+}, n = (t) => {
+	if (typeof t != "object" || !t || Array.isArray(t)) throw new e({
+		format: "form",
+		reason: `form encoding requires a JSON object at the top level, got ${l(t)}`
+	});
+	let n = new URLSearchParams();
+	for (let [e, i] of Object.entries(t)) r(n, e, i);
+	return n.toString();
+}, r = (e, t, n) => {
+	if (n === null) e.append(t, "");
+	else if (Array.isArray(n)) n.forEach((n, i) => r(e, `${t}[${i}]`, n));
+	else if (typeof n == "object") for (let [i, a] of Object.entries(n)) r(e, `${t}[${i}]`, a);
+	else e.append(t, String(n));
+}, i = /^[A-Za-z_][A-Za-z0-9_.-]*$/, a = (e) => `<?xml version="1.0" encoding="UTF-8"?>${o("webhook", e)}`, o = (t, n) => {
+	if (!i.test(t)) throw new e({
+		format: "xml",
+		reason: `object key ${JSON.stringify(t)} is not a valid XML element name`
+	});
+	return `<${t}>${s(t, n)}</${t}>`;
+}, s = (e, t) => t == null ? "" : Array.isArray(t) ? t.map((e) => o("item", e)).join("") : typeof t == "object" ? Object.entries(t).map(([e, t]) => o(e, t)).join("") : c(String(t)), c = (e) => e.replace(/[&<>"']/g, (e) => {
+	switch (e) {
+		case "&": return "&amp;";
+		case "<": return "&lt;";
+		case ">": return "&gt;";
+		case "\"": return "&quot;";
+		default: return "&apos;";
+	}
+}), l = (e) => e === null ? "null" : Array.isArray(e) ? "array" : typeof e;
+//#endregion
+export { t as encodePayload };

package/dist/eventAudience.js

@@ -0,0 +1,14 @@
+//#region src/eventAudience.ts
+var e = (e) => e.webhook !== void 0, t = (e) => {
+	let t = e.webhook;
+	if (t !== void 0) return {
+		_tag: "outgoingEvent",
+		id: e.name,
+		payload: e.payload,
+		...t.description === void 0 ? {} : { description: t.description },
+		...t.version === void 0 ? {} : { version: t.version },
+		...t.rateLimit === void 0 ? {} : { globalRateLimit: t.rateLimit }
+	};
+};
+//#endregion
+export { t as asOutgoingEvent, e as hasWebhookAudience };

package/dist/idempotency.js

@@ -0,0 +1,49 @@
+//#region src/idempotency.ts
+var e = class {
+	capacity;
+	cache = /* @__PURE__ */ new Map();
+	constructor(e = 1e4) {
+		this.capacity = e;
+	}
+	evictExpired() {
+		let e = Date.now();
+		for (let [t, n] of this.cache) n.expiresAt < e && this.cache.delete(t);
+	}
+	claim(e, t) {
+		let n = this.cache.get(e);
+		if (n !== void 0 && n.expiresAt > Date.now()) return this.cache.delete(e), this.cache.set(e, n), n.value === "inflight" ? "inflight" : "duplicate";
+		if (this.cache.set(e, {
+			value: "inflight",
+			expiresAt: Date.now() + t
+		}), this.cache.size > this.capacity) {
+			let e = this.cache.keys().next().value;
+			e !== void 0 && this.cache.delete(e);
+		}
+		return "fresh";
+	}
+	commit(e) {
+		let t = this.cache.get(e);
+		t !== void 0 && this.cache.set(e, {
+			value: "processed",
+			expiresAt: t.expiresAt
+		});
+	}
+	release(e) {
+		this.cache.delete(e);
+	}
+	size() {
+		return this.evictExpired(), this.cache.size;
+	}
+	clear() {
+		this.cache.clear();
+	}
+}, t = null, n = () => (t === null && (t = new e()), t), r = {
+	"5m": 3e5,
+	"1h": 36e5,
+	"6h": 216e5,
+	"1d": 864e5,
+	"7d": 6048e5,
+	"30d": 2592e6
+}, i = (e) => e === void 0 ? r["7d"] : r[e] ?? r["7d"];
+//#endregion
+export { e as IdempotencyCache, n as getIdempotencyCache, i as parseTtl };