@homeflare/alchemy 0.30.0 → 0.31.0

package/src/discord/resource.ts

@@ -0,0 +1,164 @@
+/**
+ * One shape for every Discord application-command object — global and guild-scoped alike.
+ *
+ * ⛔ THE ALTERNATIVE IS COPYING THE SAME READ/RECONCILE/DELETE PER RESOURCE. `application-command.ts`
+ *   and `guild-application-command.ts` differ only in which distilled operations they call and
+ *   whether `guild_id` is part of identity — so the read/diff/reconcile/delete flow lives here
+ *   once, mirroring `../netbox/resource.ts`'s `netboxOperations`/`netboxHandlers` split.
+ *
+ * ★ UNLIKE NETBOX, THIS FOLLOWS UPSTREAM'S `Snippet.ts` READ/RECONCILE SHAPE EXACTLY (S7–S9), NOT
+ *   netbox's "adopt silently" gap (H1). Discord commands carry no ownership marker of any kind —
+ *   no tags, no metadata field a bot could stamp — so this is precisely the "marker-less API" S8
+ *   describes, and `Snippet.ts@v2.0.0-beta.79#read` is the cited reference: an existing match is
+ *   `Unowned(attrs)` on a cold read (no persisted `output`), and plain attributes on a warm read
+ *   (persisted `output` says we already made or adopted this exact command). `adopt(true)` (H5),
+ *   piped onto each resource by the constructors in the two resource files, is what turns that
+ *   `Unowned` into a silent one-time takeover instead of an `OwnedBySomeoneElse` refusal.
+ *
+ * ★ RECONCILE IS ONE UPSERT CALL, LIKE `Snippet.ts`'s `putSnippet`. Discord's own docs for both
+ *   Create Global/Guild Application Command say a command with the same name (and type) as an
+ *   existing one OVERWRITES it — the create endpoint is a true upsert, not a create-only call that
+ *   409s on a name collision. ⚠️ REASONED NOT MEASURED (no token available to this task; see
+ *   `docs/discord.md`): this is Discord's documented behaviour, unchanged across API v10, but it
+ *   has not been exercised against the real API by this change. One call therefore converges
+ *   greenfield create, routine update AND adoption alike — there is no separate PATCH path, and
+ *   S10's "zero write calls when there is no drift" is still honoured because `reconcile` skips
+ *   the call entirely when `spec.matches` already holds.
+ *
+ * ⚠️ `list` ANSWERS EMPTY, ON PURPOSE, EVEN THOUGH THE DISTILLED LIST OPERATIONS EXIST. A bot's
+ *   guild command set is exactly what `hf-discord-halibut.service` bulk-overwrites at every
+ *   restart (see `docs/discord.md#halibut`); a `nuke` that enumerated and swept every live command
+ *   would fight that ownership, not just this resource's own declarations. Adoption stays
+ *   explicit, the same reasoning netbox's `list` gives for a shared instance predating the kit.
+ */
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import type { DiscordOpContext } from '@distilled.cloud/discord/Protocol';
+import * as Effect from 'effect/Effect';
+import type * as HttpClient from 'effect/unstable/http/HttpClient';
+import { CredentialsFromEnv } from './credentials.ts';
+
+/**
+ * What every stack must still provide after `discordHandlers` bakes in `CredentialsFromEnv`
+ * (below): the transport. `DiscordOpContext` is `Credentials | HttpClient.HttpClient`, so once
+ * `Credentials` is supplied, `HttpClient.HttpClient` is what remains — mirroring
+ * `../netbox/resource.ts#NetboxRequirements`.
+ */
+export type DiscordRequirements = HttpClient.HttpClient;
+
+/** Every Discord command resource's identity key, regardless of scope. */
+export interface DiscordCommandIdentity {
+  readonly name: string;
+}
+
+/**
+ * One Discord command object's distilled calls. `Live` is whatever the SDK decodes
+ * (`ApplicationCommandResponse`); `E` is left to each resource file to declare, so a call site's
+ * precise error union (in practice always `DiscordOpError` — see `protocol.ts` — because every
+ * generated Discord operation shares one error channel) flows straight through.
+ */
+export type DiscordSpec<
+  Props extends DiscordCommandIdentity,
+  Live,
+  Attributes extends object,
+  E,
+> = {
+  /** Locate the live command by its declared name within this spec's scope (app, or app+guild). */
+  readonly fetchByName: (props: Props) => Effect.Effect<Live | undefined, E, DiscordOpContext>;
+  readonly attributes: (live: Live) => Attributes;
+  readonly matches: (attributes: Attributes, props: Props) => boolean;
+  readonly upsertBody: (props: Props) => Record<string, unknown>;
+  /** POST create-or-overwrite — see the upsert note above. */
+  readonly upsert: (
+    props: Props,
+    body: Record<string, unknown>,
+  ) => Effect.Effect<Live, E, DiscordOpContext>;
+  readonly destroy: (props: Props, live: Live) => Effect.Effect<unknown, E, DiscordOpContext>;
+  /** For error messages and test descriptions. */
+  readonly describe: (props: Props) => string;
+};
+
+export const discordOperations = <
+  Props extends DiscordCommandIdentity,
+  Live,
+  Attributes extends object,
+  E,
+>(
+  spec: DiscordSpec<Props, Live, Attributes, E>,
+) => ({
+  read: ({ olds, output }: { olds: Props; output: Attributes | undefined }) =>
+    Effect.gen(function* () {
+      const live = yield* spec.fetchByName(olds);
+      if (live === undefined) return undefined;
+      const attrs = spec.attributes(live);
+      // Warm read: a prior apply already created or adopted this exact command — ours.
+      if (output !== undefined) return attrs;
+      // Cold read (fresh store, or state lost): no ownership marker exists on this vendor,
+      // so any match is `Unowned` until `adopt(true)` (or `--adopt`) says otherwise (S7, S8).
+      return Unowned(attrs);
+    }),
+
+  diff: (news: Input<Props>, output: Attributes | undefined) =>
+    Effect.gen(function* () {
+      if (output === undefined || !isResolved(news)) return undefined;
+      const live = yield* spec.fetchByName(news);
+      if (live === undefined) return { action: 'update' } as const;
+      return spec.matches(spec.attributes(live), news)
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: (news: Props) =>
+    Effect.gen(function* () {
+      const before = yield* spec.fetchByName(news);
+      if (before !== undefined && spec.matches(spec.attributes(before), news)) {
+        // Already exactly what is declared — S10: no write.
+        return spec.attributes(before);
+      }
+      const body = spec.upsertBody(news);
+      const after = yield* spec.upsert(news, body);
+      return spec.attributes(after);
+    }),
+
+  // ⚠️ GAP, NOT SOLVED: a TOCTOU race between the fetch above and the delete call below could
+  //   see Discord answer 404 on a command that vanished between the two — S11 asks that race to
+  //   be treated as success, `catchTag('NotFound', …)`. The SDK's declared error type for every
+  //   operation does not include `NotFound` (see `docs/discord.md#sdk-gaps` — measured, not
+  //   assumed), so there is no typed tag to catch here without an unsafe cast. Left unhandled.
+  destroy: (olds: Props) =>
+    Effect.gen(function* () {
+      const live = yield* spec.fetchByName(olds);
+      if (live === undefined) return;
+      yield* spec.destroy(olds, live);
+    }),
+});
+
+/**
+ * The four provider handlers for a spec'd Discord command, wired once.
+ *
+ * ★ CREDENTIALS ARE PROVIDED HERE, ONCE. `CredentialsFromEnv` resolves `DISCORD_BOT_TOKEN` /
+ *   `DISCORD_TOKEN` on the calling fiber per request (credentials.ts), so this closure keeps that
+ *   laziness — nothing is captured at module load.
+ */
+export const discordHandlers = <
+  Props extends DiscordCommandIdentity,
+  Live,
+  Attributes extends object,
+  E,
+>(
+  spec: DiscordSpec<Props, Live, Attributes, E>,
+) => {
+  const ops = discordOperations(spec);
+  const withCredentials = <A>(effect: Effect.Effect<A, E, DiscordOpContext>) =>
+    Effect.provide(effect, CredentialsFromEnv);
+  return {
+    list: () => Effect.succeed([]),
+    read: ({ olds, output }: { olds: Props; output: Attributes | undefined }) =>
+      withCredentials(ops.read({ olds, output })),
+    diff: ({ news, output }: { news: Input<Props>; output: Attributes | undefined }) =>
+      withCredentials(ops.diff(news, output)),
+    reconcile: ({ news }: { news: Props }) => withCredentials(ops.reconcile(news)),
+    delete: ({ olds }: { olds: Props }) => withCredentials(ops.destroy(olds)),
+  };
+};

package/src/discord/retry.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Discord's 429 handling — proving the SDK's OWN default retry policy (`@distilled.cloud/core`'s
+ * `makeDefault`, threaded through every operation via `retry: Retry.Retry` — see `resource.ts`'s
+ * header note and `docs/discord.md#rate-limits`), not a house re-implementation. This file exists
+ * because "respect Discord's rate limits with a bounded retry" is a requirement this task must
+ * satisfy, and the honest way to satisfy it here is to prove the SDK already does — nothing in
+ * `resource.ts` installs a `Discord.Retry.policy` of its own, so if this test ever failed to
+ * retry, or failed to STOP retrying, there would be nothing in this package to fix; the fix would
+ * be in `@distilled.cloud/discord`.
+ *
+ * ⛔ A TEST THAT CANNOT FAIL PROVES NOTHING. Both cases below assert on the fake's own call count
+ *   (`fake.seen.length`), not just on the eventual Effect outcome — a policy that retried once,
+ *   or one that retried forever, would each still "eventually succeed" or "eventually fail" on
+ *   SOME outcome; the call count is what makes "bounded" a real, checkable claim rather than an
+ *   assumption the test's own passing would not have caught.
+ */
+import { describe, expect, test } from 'bun:test';
+import * as Effect from 'effect/Effect';
+import { spec } from './guild-application-command.ts';
+import type { GuildApplicationCommandProps } from './guild-application-command.ts';
+import { fakeDiscord, fakeDiscordLayer, fakeRateLimited } from './fake-discord.ts';
+
+const APP = '111111111111111111';
+const GUILD = '222222222222222222';
+const CMD_PATH = `/applications/${APP}/guilds/${GUILD}/commands`;
+const PROPS: GuildApplicationCommandProps = { applicationId: APP, guildId: GUILD, name: 'ping' };
+
+const liveCommand = () => ({
+  application_id: APP,
+  default_member_permissions: null,
+  description: '',
+  guild_id: GUILD,
+  id: '999',
+  name: 'ping',
+  nsfw: false,
+  type: 1,
+  version: '1',
+});
+
+describe('the SDK default Retry policy on a 429', () => {
+  test('two 429s (Retry-After: 0) then a 200 — retried, and it converges', async () => {
+    const fake = fakeDiscord((method, url, _body, callNumber) => {
+      if (method !== 'GET' || url.pathname !== CMD_PATH) return new Response(null, { status: 500 });
+      return callNumber <= 2 ? fakeRateLimited(0) : Response.json([liveCommand()]);
+    });
+    const live = await Effect.runPromise(
+      spec.fetchByName(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch))),
+    );
+    expect(live?.id).toBe('999');
+    expect(fake.seen).toHaveLength(3);
+  }, 15_000);
+
+  /**
+   * ★ THE BOUND ITSELF. `@distilled.cloud/core`'s `makeDefault` caps this at `Schedule.recurs(8)`
+   *   — 8 retries, 9 attempts total — regardless of how long the server keeps answering 429. A
+   *   server that never recovers must still let the caller find out, in bounded time, rather than
+   *   parking the fiber forever; that is the literal meaning of "bounded retry".
+   */
+  test('429 forever is a bounded number of attempts, then a typed failure — never an infinite loop', async () => {
+    const fake = fakeDiscord((method, url) =>
+      method === 'GET' && url.pathname === CMD_PATH
+        ? fakeRateLimited(0)
+        : new Response(null, { status: 500 }),
+    );
+    const failure = await Effect.runPromise(
+      Effect.flip(spec.fetchByName(PROPS).pipe(Effect.provide(fakeDiscordLayer(fake.fetch)))),
+    );
+    expect(failure._tag).toBe('TooManyRequests');
+    // 1 initial attempt + at most 8 retries. Strictly greater than 1 proves a retry happened at
+    // all; at most 9 proves it stopped rather than continuing past the documented bound.
+    expect(fake.seen.length).toBeGreaterThan(1);
+    expect(fake.seen.length).toBeLessThanOrEqual(9);
+  }, 15_000);
+});