The best way to control Claude Code, Codex and more from any computer or phone

main
ts 116 lines 3.81 KB
Raw
1 import * as Binding from "alchemy/Binding";
2 import type * as Effect from "effect/Effect";
3 import type { RetryConfig } from "./Job.ts";
4
5 /** One Cloud Scheduler invocation. */
6 export interface ScheduledEvent {
7 /** RFC3339 time the run was scheduled for (`X-CloudScheduler-ScheduleTime`). */
8 scheduleTime: string;
9 /** Short id of the job that fired (`X-CloudScheduler-JobName`). */
10 jobName: string;
11 /** The job's configured request body, if any. */
12 body: string | undefined;
13 }
14
15 export interface ScheduleEventSourceProps {
16 /**
17 * Cron (`"0 * * * *"`) or english-like (`"every 5 minutes"`) schedule.
18 */
19 schedule: string;
20 /**
21 * tz-database time zone used to interpret `schedule`.
22 * @default "Etc/UTC"
23 */
24 timeZone?: string;
25 /** UTF-8 body sent with every invocation. */
26 body?: string;
27 /**
28 * Cloud Scheduler location of the backing job.
29 * @default the stack's GCP region (`GCP.Region`, profile region, `us-central1`)
30 */
31 location?: string;
32 /**
33 * Retry policy for failed invocations. The default retries a refused or
34 * failed delivery (e.g. while a new invoker grant propagates) instead
35 * of dropping that run.
36 * @default { retryCount: 5, minBackoffDuration: "10s", maxBackoffDuration: "120s" }
37 */
38 retryConfig?: RetryConfig;
39 /**
40 * Delivery path on the host. Defaults to a deterministic per-schedule
41 * path under `/__alchemy/scheduler/`.
42 */
43 path?: string;
44 }
45
46 export type ScheduledEventHandler<Req> = (event: ScheduledEvent) => Effect.Effect<void, never, Req>;
47
48 export type ScheduleEventSourceService = <Req = never>(
49 id: string,
50 props: ScheduleEventSourceProps,
51 process: ScheduledEventHandler<Req>,
52 ) => Effect.Effect<void, never, never>;
53
54 /**
55 * Event source that invokes the hosting compute on a Cloud Scheduler
56 * schedule — the "cron handler" DX.
57 *
58 * The HTTP-host implementation is `GCP.Run.ScheduleEventSource`
59 * (`GCP.Function` / `GCP.Run.Service`, `GCP.CloudFunctions.Function`): it
60 * creates a Cloud Scheduler job that `POST`s to the host with an OIDC
61 * token for the host's runtime service account, grants that account
62 * `roles/run.invoker` on the host, and verifies the token on every
63 * invocation. A failed handler answers 500 and the job's retry policy
64 * applies.
65 *
66 * Consume it through {@link consumeSchedule}.
67 *
68 * ### Consuming a Schedule
69 * **Example:** Nightly cleanup on a Cloud Run service
70 * ```typescript
71 * export class Api extends GCP.Function<Api>()(
72 * "Api",
73 * { main: import.meta.url },
74 * Effect.gen(function* () {
75 * yield* GCP.CloudScheduler.consumeSchedule(
76 * "NightlyCleanup",
77 * { schedule: "0 3 * * *", timeZone: "America/New_York" },
78 * (event) => Effect.log(`cleanup scheduled for ${event.scheduleTime}`),
79 * );
80 * }).pipe(Effect.provide(GCP.Run.ScheduleEventSource)),
81 * ) {}
82 * ```
83 *
84 * **Example:** Pass a fixed payload
85 * ```typescript
86 * yield* GCP.CloudScheduler.consumeSchedule(
87 * "Digest",
88 * { schedule: "every 1 hours", body: JSON.stringify({ kind: "digest" }) },
89 * (event) => sendDigest(JSON.parse(event.body ?? "{}")),
90 * );
91 * ```
92 *
93 * @binding
94 * @category CloudScheduler
95 */
96 export interface ScheduleEventSource extends Binding.Service<
97 ScheduleEventSource,
98 "GCP.CloudScheduler.ScheduleEventSource",
99 ScheduleEventSourceService
100 > {}
101
102 export const ScheduleEventSource = Binding.Service<ScheduleEventSource>(
103 "GCP.CloudScheduler.ScheduleEventSource",
104 );
105
106 /**
107 * Run an Effect handler on a Cloud Scheduler schedule. `id` names the
108 * backing job and its delivery route; keep it stable. See
109 * {@link ScheduleEventSource} for the host implementations.
110 */
111 export const consumeSchedule = <Req = never>(
112 id: string,
113 props: ScheduleEventSourceProps,
114 process: ScheduledEventHandler<Req>,
115 ): Effect.Effect<void, never, ScheduleEventSource> =>
116 ScheduleEventSource.use((source) => source(id, props, process));