@astrale-os/adapter-cloudflare 0.1.8 → 0.1.10

package/template/integrations/prober/http.ts

@@ -0,0 +1,43 @@
+/**
+ * HTTP prober — the REAL external adapter: a single keyless `fetch` to the
+ * target, timing the round-trip. This is the shape your domain's external calls
+ * take — a timeout via `AbortSignal`, failures mapped to a domain result rather
+ * than thrown. NO API key: a fresh scaffold makes a true external call out of
+ * the box (it's the registry default).
+ */
+import type { Prober, ProbeResult } from './port'
+
+export interface HttpProberConfig {
+  /** Probe verb — `GET` (default) or the lighter `HEAD`. */
+  method?: 'GET' | 'HEAD'
+  /** Per-probe timeout in ms (default 10000). */
+  timeoutMs?: number
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000
+
+/** Build the keyless HTTP prober. */
+export function createHttpProber(config: HttpProberConfig = {}): Prober {
+  const method = config.method ?? 'GET'
+  const timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS
+  return {
+    async probe(url): Promise<ProbeResult> {
+      const start = Date.now()
+      try {
+        const res = await fetch(url, {
+          method,
+          redirect: 'follow',
+          signal: AbortSignal.timeout(timeoutMs),
+        })
+        return {
+          statusCode: res.status,
+          latencyMs: Date.now() - start,
+          ok: res.status >= 200 && res.status < 400,
+        }
+      } catch {
+        // Unreachable / timeout / DNS failure — a `down` result, not an error.
+        return { statusCode: 0, latencyMs: Date.now() - start, ok: false }
+      }
+    },
+  }
+}

package/template/integrations/prober/mock.ts

@@ -0,0 +1,22 @@
+/**
+ * Mock prober — offline + deterministic, no network. Used by tests (construct it
+ * directly with the status you want) and by `PROBER=mock` for an offline dev
+ * loop. Returns a fixed result regardless of URL.
+ */
+import type { Prober, ProbeResult } from './port'
+
+/** Build an offline prober that always returns `opts` (default: a healthy 200). */
+export function createMockProber(opts: { statusCode?: number; latencyMs?: number } = {}): Prober {
+  const statusCode = opts.statusCode ?? 200
+  const latencyMs = opts.latencyMs ?? 1
+  const result: ProbeResult = {
+    statusCode,
+    latencyMs,
+    ok: statusCode >= 200 && statusCode < 400,
+  }
+  return {
+    probe() {
+      return Promise.resolve(result)
+    },
+  }
+}

package/template/integrations/prober/port.ts

@@ -0,0 +1,28 @@
+/**
+ * Prober — the PORT between the domain's logic and whatever performs the actual
+ * uptime probe. This is the external-API seam every real domain has, reduced to
+ * the narrowest interface the logic needs.
+ *
+ * `runtime/` logic depends on THIS interface only — never on `fetch`, an SDK, or
+ * `env`. Adapters in this folder implement it: `http.ts` (a real, keyless HTTP
+ * request) and `mock.ts` (offline + deterministic, for tests). The registry
+ * picks one from `env`; the handler logic only ever sees the resolved port. Swap
+ * or add a backend = one adapter + one arm in `registry.ts`.
+ */
+export interface ProbeResult {
+  /** Observed HTTP status code, or `0` if the host was unreachable. */
+  statusCode: number
+  /** Round-trip time in ms. */
+  latencyMs: number
+  /** Convenience flag — `statusCode` in `[200, 400)`. */
+  ok: boolean
+}
+
+export interface Prober {
+  /**
+   * Probe a URL once. MUST resolve, never reject: an unreachable host or a
+   * timeout is a `down` RESULT (`statusCode: 0`), not an error — a probe failing
+   * is the normal case a monitor exists to observe.
+   */
+  probe(url: string): Promise<ProbeResult>
+}

package/template/integrations/prober/registry.ts

@@ -0,0 +1,66 @@
+/**
+ * Prober registry — the ONE place the worker env (and the probed node) become the
+ * live `Prober` port. Adding a backend = one more arm in `selectProber`; handler
+ * logic only ever sees the resolved port.
+ *
+ * Resolution is PER-REQUEST and PER-NODE: each `prober(target)` call selects +
+ * builds the port from env AND the monitor being probed — nothing is built at
+ * `deps()` / isolate setup. A per-node choice can't be memoized at the isolate
+ * level, which is exactly why `deps` exposes `prober()` as a FUNCTION, not a
+ * value. The default is the keyless `http` prober (so the scaffold makes a real
+ * probe out of the box); `PROBER=mock` forces the offline prober.
+ */
+import type { Env } from '../../env'
+import type { Prober } from './port'
+
+import { createHttpProber } from './http'
+import { createMockProber } from './mock'
+
+/**
+ * The node a probe is for — what the registry may branch on. Mirrors how the
+ * `services` domain picks a provider from a node's class; here we also look at
+ * the target url. The handler passes this from `self.node()`; omit it for
+ * node-less callers (e.g. `seed`, which just wants the env default).
+ */
+export interface ProbeTarget {
+  /** The monitor node's class path (`node.class.raw`). */
+  class: string
+  /** The url this monitor probes (`node.props[MONITOR_KEYS.url]`). */
+  url: string
+}
+
+export interface ProberRegistry {
+  /** Resolve the prober for a probe — built per call from env + the target node. */
+  prober(target?: ProbeTarget): Prober
+}
+
+/** Build the registry from the worker env. The port is resolved per request. */
+export function buildProberRegistry(env: Env): ProberRegistry {
+  return {
+    prober(target) {
+      return selectProber(env, target)
+    },
+  }
+}
+
+const DEFAULT_TIMEOUT_MS = 10_000
+
+/** Bind the abstract prober port to the concrete adapter for this env + target. */
+function selectProber(env: Env, target?: ProbeTarget): Prober {
+  if (target && isLocalTarget(target.url)) {
+    return createMockProber()
+  }
+  // Default: the real, keyless HTTP prober.
+  return createHttpProber({ timeoutMs: parseIntOr(env.PROBE_TIMEOUT_MS, DEFAULT_TIMEOUT_MS) })
+}
+
+/** A loopback / unspecified host the public edge can't reach. */
+function isLocalTarget(url: string): boolean {
+  return /^https?:\/\/(localhost|127\.0\.0\.1|0\.0\.0\.0|\[::1\])(:|\/|$)/i.test(url)
+}
+
+function parseIntOr(value: string | undefined, fallback: number): number {
+  if (!value) return fallback
+  const n = Number.parseInt(value, 10)
+  return Number.isFinite(n) && n > 0 ? n : fallback
+}

package/template/package.json

@@ -14,11 +14,10 @@
     "typecheck": "tsgo --noEmit"
   },
   "dependencies": {
-    "@astrale-os/adapter-cloudflare": ">=0.1.7 <1.0.0",
-    "@astrale-os/devkit": ">=0.1.6 <1.0.0",
+    "@astrale-os/adapter-cloudflare": ">=0.1.10 <1.0.0",
     "@astrale-os/kernel-core": ">=0.4.3 <1.0.0",
     "@astrale-os/kernel-dsl": ">=0.1.2 <1.0.0",
-    "@astrale-os/sdk": ">=0.1.5 <1.0.0",
+    "@astrale-os/sdk": ">=0.1.7 <1.0.0",
     "@hono/node-server": "^1.19.0",
     "zod": "^4.3.6"
   },