@homeflare/alchemy 0.23.0 → 0.25.0

package/src/litellm/pass-through-endpoint-replace.test.ts

@@ -0,0 +1,84 @@
+/**
+ * `LiteLLM.PassThroughEndpoint`'s `replace` (clearing `timeout`/`methods`/`guardrails`), through
+ * Alchemy's own `Plan.make`/`apply` (fake-stack.ts) — not the handlers called directly.
+ *
+ * ⛔ BUG: before this file's fix, `diff` answered `{ action: 'replace' }` with no `deleteFirst`.
+ *   Per `Apply.ts`, that is CREATE-FIRST: the engine mints a fresh `instanceId` and calls
+ *   `reconcile` for the new generation with `output: undefined, olds: undefined`, deleting the old
+ *   generation only afterwards, by a SEPARATE `provider.delete()` call under the OLD instanceId.
+ *   Since `objectId` is derived from `instanceId` (`physicalIdOf`/`createPhysicalName`), the new
+ *   generation's id differs from the still-live old row on the same `path`. `reconcile`'s own
+ *   `locate()` then finds that old row as a `conflict` on `path` (not `mine`, since the id differs)
+ *   and refuses with `LitellmUnaddressableRowError` — misidentifying its own prior generation as a
+ *   foreign, unaddressable row. Every real deploy that clears one of the three nullable fields
+ *   failed outright. `pass-through-endpoint.test.ts`'s own 'clearing a nullable field' test never
+ *   caught this: it calls `h.reconcile` directly with the SAME instanceId and the OLD output, a
+ *   call shape the real engine never produces for a `replace`.
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import * as RemovalPolicy from 'alchemy/RemovalPolicy';
+import * as Effect from 'effect/Effect';
+import { type FakeStack, fakeStack, writesOf } from './fake-stack.ts';
+import { type FakeLitellm, startFakeLitellm } from './fake-litellm.ts';
+import { LiteLLMPassThroughEndpoint } from './pass-through-endpoint.ts';
+import type { PassThroughEndpointProps } from './pass-through-form.ts';
+
+const MASTER_KEY = 'sk-test-master';
+
+let fake: FakeLitellm;
+let stack: FakeStack;
+beforeEach(() => {
+  fake = startFakeLitellm({ masterKey: MASTER_KEY });
+  stack = fakeStack({ apiKey: MASTER_KEY, baseUrl: fake.url });
+});
+afterEach(() => fake.stop());
+
+/** ★ `RemovalPolicy.destroy()`, deliberately: under the (non-default) `retain`, `deleteFirst`'s own
+ *   old-generation delete is skipped by the engine (Apply.ts's `deleteOldGenerations`), so a path
+ *   that cannot hold two rows stays conflicted either way — a documented engine limitation
+ *   (openbao/REPLACE.md), not this provider's bug, and out of scope for this fix. */
+const declare = (props: PassThroughEndpointProps) =>
+  Effect.asVoid(LiteLLMPassThroughEndpoint('Endpoint', props).pipe(RemovalPolicy.destroy()));
+
+describe('clearing a nullable field, through the engine', () => {
+  test('plans replace and leaves exactly one live row on the path, never two, never zero', async () => {
+    const withTimeout: PassThroughEndpointProps = {
+      path: '/bria',
+      target: 'https://api.bria.ai',
+      timeout: 30,
+    };
+    const cleared: PassThroughEndpointProps = { path: '/bria', target: 'https://api.bria.ai' };
+
+    expect(await stack.deploy(declare(withTimeout))).toEqual({ Endpoint: 'create' });
+    const oldId = fake.rows().find((r) => r.path === '/bria')?.id;
+    expect(oldId).toBeDefined();
+
+    const planned = await stack.deploy(declare(cleared));
+
+    expect(planned).toEqual({ Endpoint: 'replace' });
+    const onPath = fake.rows().filter((r) => r.path === '/bria');
+    expect(onPath).toHaveLength(1);
+    expect(onPath[0]?.timeout).toBeUndefined();
+    // ★ deleteFirst: the old generation's id is gone; the surviving row is a NEW generation, not
+    //   the old row merely left with a stale `timeout` because the write silently no-op'd.
+    expect(onPath[0]?.id).not.toBe(oldId);
+  });
+
+  test('deletes the old generation before creating the new one on the same path', async () => {
+    const withTimeout: PassThroughEndpointProps = {
+      path: '/bria',
+      target: 'https://api.bria.ai',
+      timeout: 30,
+    };
+    const cleared: PassThroughEndpointProps = { path: '/bria', target: 'https://api.bria.ai' };
+    await stack.deploy(declare(withTimeout));
+    const before = fake.requests().length;
+
+    await stack.deploy(declare(cleared));
+
+    const writes = writesOf(fake.requests().slice(before));
+    // create-first would be [POST, DELETE]; a `path` that cannot hold two rows needs delete-first.
+    expect(writes[0]?.startsWith('DELETE')).toBe(true);
+    expect(writes.some((w) => w.startsWith('POST /config/pass_through_endpoint'))).toBe(true);
+  });
+});

package/src/litellm/pass-through-endpoint.test.ts

@@ -0,0 +1,208 @@
+/**
+ * `LiteLLM.PassThroughEndpoint`'s lifecycle handlers, called directly against `fake-litellm.ts` —
+ * the loopback-fake pattern this kit uses in place of `alchemy/Test/*` (H12, no live writes).
+ */
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { Stack } from 'alchemy/Stack';
+import { Stage } from 'alchemy/Stage';
+import * as Effect from 'effect/Effect';
+import * as FetchHttpClient from 'effect/unstable/http/FetchHttpClient';
+import { litellmCredentialsLayerFor } from './credentials.ts';
+import { type FakeLitellm, startFakeLitellm } from './fake-litellm.ts';
+import { createPassThroughEndpoint } from './client.ts';
+import {
+  LitellmConfigPathConflictError,
+  LitellmLiteralSecretHeaderError,
+  type PassThroughEndpointProps,
+  passThroughHandlers as h,
+} from './pass-through-endpoint.ts';
+
+const MASTER_KEY = 'sk-test-master';
+const INSTANCE_ID = 'a'.repeat(32);
+const FAKE_STACK = { actions: {}, bindings: {}, name: 's', resources: {}, stage: 'test' } as never;
+
+let fake: FakeLitellm;
+beforeEach(() => {
+  fake = startFakeLitellm({ masterKey: MASTER_KEY });
+});
+afterEach(() => fake.stop());
+
+const run = <A, E>(effect: Effect.Effect<A, E, never>): Promise<A> =>
+  Effect.runPromise(effect as Effect.Effect<A, E, never>);
+
+const withServices = <A, E, R>(effect: Effect.Effect<A, E, R>) =>
+  effect.pipe(
+    Effect.provide(FetchHttpClient.layer),
+    Effect.provide(litellmCredentialsLayerFor({ apiKey: MASTER_KEY, baseUrl: fake.url })),
+    Effect.provideService(Stage, 'test'),
+    Effect.provideService(Stack, FAKE_STACK),
+  ) as Effect.Effect<A, E, never>;
+
+const PROPS: PassThroughEndpointProps = { path: '/bria', target: 'https://api.bria.ai' };
+const reconcileNew = (news: PassThroughEndpointProps) =>
+  run(
+    withServices(h.reconcile({ id: 'Endpoint', instanceId: INSTANCE_ID, news, output: undefined })),
+  );
+
+describe('create then plan again', () => {
+  test('a second read/diff against the same declaration is noop, with no write', async () => {
+    const attrs = await reconcileNew(PROPS);
+    const before = fake.requests().length;
+    const read = await run(
+      withServices(h.read({ id: 'Endpoint', instanceId: INSTANCE_ID, olds: PROPS, output: attrs })),
+    );
+    const diff = await run(withServices(h.diff({ news: PROPS, output: read })));
+    expect(diff).toEqual({ action: 'noop' });
+    expect(
+      fake
+        .requests()
+        .slice(before)
+        .some((r) => r.method !== 'GET'),
+    ).toBe(false);
+  });
+});
+
+describe('a header edit', () => {
+  test('is one POST /{id} carrying the whole headers dict', async () => {
+    const attrs = await reconcileNew(PROPS);
+    const before = fake.requests().length;
+    const news = { ...PROPS, headers: { 'X-Client': 'v2' } };
+    await run(
+      withServices(h.reconcile({ id: 'Endpoint', instanceId: INSTANCE_ID, news, output: attrs })),
+    );
+    const writes = fake
+      .requests()
+      .slice(before)
+      .filter((r) => r.method !== 'GET');
+    expect(writes).toEqual([{ method: 'POST', path: `/config/pass_through_endpoint/${attrs.id}` }]);
+    expect(fake.rows().find((r) => r.id === attrs.id)?.headers).toEqual({ 'X-Client': 'v2' });
+  });
+});
+
+describe('clearing a nullable field', () => {
+  test('is a replace: delete before create, never two rows on one path', async () => {
+    const attrs = await reconcileNew({ ...PROPS, timeout: 30 });
+    const oldId = attrs.id;
+    const before = fake.requests().length;
+    const after = await run(
+      withServices(
+        h.reconcile({ id: 'Endpoint', instanceId: INSTANCE_ID, news: PROPS, output: attrs }),
+      ),
+    );
+    const writes = fake
+      .requests()
+      .slice(before)
+      .filter((r) => r.method !== 'GET')
+      .map((r) => r.method);
+    expect(writes).toEqual(['DELETE', 'POST']);
+    expect(fake.rows().filter((r) => r.path === '/bria')).toHaveLength(1);
+    expect(after.id).toBe(oldId); // same deterministic id, recreated
+    expect(after.timeout).toBeUndefined();
+  });
+});
+
+describe('delete', () => {
+  test('an already-gone id succeeds with no DELETE call', async () => {
+    const attrs = await reconcileNew(PROPS);
+    await run(
+      withServices(
+        h.delete({ id: 'Endpoint', instanceId: INSTANCE_ID, olds: PROPS, output: attrs }),
+      ),
+    );
+    const before = fake.requests().length;
+    await run(
+      withServices(
+        h.delete({ id: 'Endpoint', instanceId: INSTANCE_ID, olds: PROPS, output: attrs }),
+      ),
+    );
+    expect(
+      fake
+        .requests()
+        .slice(before)
+        .some((r) => r.method === 'DELETE'),
+    ).toBe(false);
+  });
+});
+
+describe('two endpoints created in one deploy', () => {
+  /** ⛔ Fails without client.ts's per-base-URL semaphore — the fake's race window (RACE_WINDOW_MS) proves it. */
+  test('both survive the shared general_settings field', async () => {
+    const a: PassThroughEndpointProps = { path: '/a', target: 'https://a.example.com' };
+    const b: PassThroughEndpointProps = { path: '/b', target: 'https://b.example.com' };
+    await Effect.runPromise(
+      Effect.all(
+        [
+          withServices(createPassThroughEndpoint({ ...a, id: 'ep-a' })),
+          withServices(createPassThroughEndpoint({ ...b, id: 'ep-b' })),
+        ],
+        { concurrency: 'unbounded' },
+      ),
+    );
+    expect(
+      fake
+        .rows()
+        .map((r) => r.path)
+        .sort(),
+    ).toEqual(['/a', '/b']);
+  });
+});
+
+describe('a path held by an is_from_config row', () => {
+  test('is refused at read, before any write', async () => {
+    fake.stop();
+    fake = startFakeLitellm({
+      masterKey: MASTER_KEY,
+      seed: [{ ...PROPS, id: 'cfg-1', is_from_config: true }],
+    });
+    const result = run(
+      withServices(
+        h.read({ id: 'Endpoint', instanceId: INSTANCE_ID, olds: PROPS, output: undefined }),
+      ),
+    );
+    await expect(result).rejects.toThrow(LitellmConfigPathConflictError as never);
+    expect(fake.requests().every((r) => r.method === 'GET')).toBe(true);
+  });
+});
+
+describe('a foreign DB row on the same path', () => {
+  test('is Unowned, and read works with output undefined', async () => {
+    fake.stop();
+    fake = startFakeLitellm({
+      masterKey: MASTER_KEY,
+      seed: [{ ...PROPS, id: 'foreign-1', is_from_config: false }],
+    });
+    const result = await run(
+      withServices(
+        h.read({ id: 'Endpoint', instanceId: INSTANCE_ID, olds: PROPS, output: undefined }),
+      ),
+    );
+    expect(Unowned.is(result)).toBe(true);
+    expect(result?.id).toBe('foreign-1');
+  });
+});
+
+describe('a literal secret header', () => {
+  test('is refused at plan (diff), before any write', async () => {
+    const news = { ...PROPS, headers: { Authorization: 'Bearer sk-live-literal' } };
+    const result = run(withServices(h.diff({ news, output: undefined })));
+    await expect(result).rejects.toThrow(LitellmLiteralSecretHeaderError as never);
+  });
+
+  test('an os.environ/ reference is accepted', async () => {
+    const news = { ...PROPS, headers: { Authorization: 'os.environ/UPSTREAM_KEY' } };
+    const diff = await run(withServices(h.diff({ news, output: undefined })));
+    expect(diff).toBeUndefined(); // output undefined -> the engine's default create
+  });
+});
+
+describe('read', () => {
+  test('with output undefined and nothing live, answers undefined (create)', async () => {
+    const result = await run(
+      withServices(
+        h.read({ id: 'Endpoint', instanceId: INSTANCE_ID, olds: PROPS, output: undefined }),
+      ),
+    );
+    expect(result).toBeUndefined();
+  });
+});

package/src/litellm/pass-through-endpoint.ts

@@ -0,0 +1,258 @@
+/**
+ * `LiteLLM.PassThroughEndpoint` — one row in LiteLLM's `general_settings.pass_through_endpoints`.
+ *
+ * ★ ADOPT-FRIENDLY BY id, NOT BY PATH. `output?.id` is used as the object's live id once the
+ *   engine has one — from our own prior create (the deterministic physical name) or from an
+ *   adopted foreign row — and `read` computes a FRESH physical name only for a resource the
+ *   engine has never resolved before. This is S7/S9's "output is a cache of stable identifiers,
+ *   not proof the object exists" and S13's "an adopted object keeps its live name as an explicit
+ *   prop", applied to an id LiteLLM lets a client choose (`_types.py:2192` at v1.100.0: create
+ *   takes a caller-supplied `id`, else `uuid4()`).
+ *
+ * ⛔ A PATH HELD BY AN `is_from_config` ROW IS REFUSED, NOT ADOPTED. A DB row on the same path
+ *   overrides it at runtime (`pass_through_endpoints.py` merges DB after config, at the tag) — so
+ *   creating one would silently take over a route the operator declared in `config.yaml`, the
+ *   exact "DB row silently overrides the file" the task names. `is_from_config` rows are also
+ *   never updated or deleted by this provider, for the same reason.
+ * ⛔ A DB ROW WITH NO `id` (path-only, `_types.py`'s "backwards compatibility" case) CANNOT BE
+ *   ADDRESSED by the id-keyed update/delete calls this provider uses, so it is refused rather than
+ *   silently adopted into an id-based lifecycle it cannot actually manage — see docs/litellm.md.
+ * ⛔ NO CREDENTIAL IS A PROP (S25). `LITELLM_PROXY_URL`/`LITELLM_PROXY_API_KEY` are read at call
+ *   time by credentials.ts.
+ */
+import { Resource } from 'alchemy';
+import { Unowned } from 'alchemy/AdoptPolicy';
+import { isResolved } from 'alchemy/Diff';
+import type { Input } from 'alchemy/Input';
+import { createPhysicalName } from 'alchemy/PhysicalName';
+import * as Provider from 'alchemy/Provider';
+import type { Stack } from 'alchemy/Stack';
+import type { Stage } from 'alchemy/Stage';
+import * as Data from 'effect/Data';
+import * as Effect from 'effect/Effect';
+import * as Predicate from 'effect/Predicate';
+import {
+  type LitellmError,
+  type LitellmRequirements,
+  createPassThroughEndpoint,
+  deletePassThroughEndpoint,
+  listPassThroughEndpoints,
+  updatePassThroughEndpoint,
+} from './client.ts';
+import type { PassThroughGenericEndpoint } from './generated/pass-through.ts';
+import {
+  type PassThroughEndpointAttributes,
+  type PassThroughEndpointProps,
+  createBody,
+  literalSecretHeaders,
+  matches,
+  needsReplace,
+  updateBody,
+} from './pass-through-form.ts';
+
+export type { PassThroughEndpointAttributes, PassThroughEndpointProps };
+
+export class LitellmConfigPathConflictError extends Data.TaggedError(
+  'LitellmConfigPathConflictError',
+)<{
+  readonly path: string;
+}> {}
+export class LitellmUnaddressableRowError extends Data.TaggedError('LitellmUnaddressableRowError')<{
+  readonly path: string;
+}> {}
+export class LitellmLiteralSecretHeaderError extends Data.TaggedError(
+  'LitellmLiteralSecretHeaderError',
+)<{
+  readonly headers: readonly string[];
+}> {}
+
+export type PassThroughEndpointError =
+  | LitellmError
+  | LitellmConfigPathConflictError
+  | LitellmUnaddressableRowError
+  | LitellmLiteralSecretHeaderError;
+
+export interface LiteLLMPassThroughEndpoint extends Resource<
+  'LiteLLM.PassThroughEndpoint',
+  PassThroughEndpointProps,
+  PassThroughEndpointAttributes,
+  never,
+  LitellmRequirements | Stack | Stage
+> {}
+
+export const LiteLLMPassThroughEndpoint = Resource<LiteLLMPassThroughEndpoint>(
+  'LiteLLM.PassThroughEndpoint',
+);
+
+export const isLiteLLMPassThroughEndpoint = (value: unknown): value is LiteLLMPassThroughEndpoint =>
+  Predicate.hasProperty(value, 'Type') && value.Type === 'LiteLLM.PassThroughEndpoint';
+
+const toAttributes = (
+  row: PassThroughGenericEndpoint,
+  fallbackId: string,
+): PassThroughEndpointAttributes => ({
+  ...row,
+  id: row.id ?? fallbackId,
+});
+
+const physicalIdOf = (logicalId: string, instanceId: string) =>
+  createPhysicalName({ id: logicalId, instanceId, lowercase: true, maxLength: 64 });
+
+/**
+ * Find this resource's live row (by id) and, when absent, the row that already holds its `path`
+ * (a config-file row to refuse, or a DB row LiteLLM did not give an id — also refused, see the
+ * file header — or a genuine foreign DB row to hand back `Unowned`).
+ */
+const locate = (
+  rows: readonly PassThroughGenericEndpoint[],
+  objectId: string,
+  path: string,
+): {
+  readonly mine: PassThroughGenericEndpoint | undefined;
+  readonly conflict: PassThroughGenericEndpoint | undefined;
+} => {
+  const mine = rows.find((row) => row.id === objectId);
+  const conflict = mine === undefined ? rows.find((row) => row.path === path) : undefined;
+  return { conflict, mine };
+};
+
+/** The typed refusal for a `path` conflict that cannot ever be adopted (config row, or no id). */
+const conflictRefusal = (conflict: PassThroughGenericEndpoint, path: string) =>
+  conflict.is_from_config === true
+    ? new LitellmConfigPathConflictError({ path })
+    : new LitellmUnaddressableRowError({ path });
+
+/** `read`'s answer for a path conflict: `Unowned` when it is a real, addressable DB row — a typed refusal otherwise. */
+const readConflict = (conflict: PassThroughGenericEndpoint, path: string) =>
+  conflict.is_from_config !== true && conflict.id !== undefined && conflict.id !== null
+    ? Effect.succeed(Unowned(toAttributes(conflict, conflict.id)))
+    : Effect.fail(conflictRefusal(conflict, path));
+
+const refuseLiteralSecrets = (headers: Readonly<Record<string, unknown>> | undefined) => {
+  const bad = literalSecretHeaders(headers);
+  return bad.length === 0
+    ? Effect.void
+    : Effect.fail(new LitellmLiteralSecretHeaderError({ headers: bad }));
+};
+
+/** ⛔ TEST-ONLY EXPORT. Not on index.ts's barrel — a lifecycle test calls these directly against the fake. */
+export const passThroughHandlers = {
+  read: ({
+    id,
+    instanceId,
+    olds,
+    output,
+  }: {
+    id: string;
+    instanceId: string;
+    olds: PassThroughEndpointProps;
+    output: PassThroughEndpointAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      const objectId = output?.id ?? (yield* physicalIdOf(id, instanceId));
+      const rows = yield* listPassThroughEndpoints();
+      const { conflict, mine } = locate(rows, objectId, olds.path);
+      if (mine !== undefined) return toAttributes(mine, objectId);
+      if (conflict === undefined) return undefined;
+      return yield* readConflict(conflict, olds.path);
+    }),
+
+  diff: ({
+    news,
+    output,
+  }: {
+    news: Input<PassThroughEndpointProps>;
+    output: PassThroughEndpointAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      if (!isResolved(news)) return undefined;
+      yield* refuseLiteralSecrets(news.headers);
+      if (output === undefined) return undefined;
+      // ⛔ deleteFirst: TRUE — a create-first replace mints a new instanceId/id before the old row
+      //   on `path` is gone, so the new generation's `reconcile` would refuse it as a foreign
+      //   conflict (Apply.ts). Same fix this kit's other unique-identity providers use.
+      if (needsReplace(output, news)) return { action: 'replace', deleteFirst: true } as const;
+      return matches(output, news)
+        ? ({ action: 'noop' } as const)
+        : ({ action: 'update' } as const);
+    }),
+
+  reconcile: ({
+    id,
+    instanceId,
+    news,
+    output,
+  }: {
+    id: string;
+    instanceId: string;
+    news: PassThroughEndpointProps;
+    output: PassThroughEndpointAttributes | undefined;
+  }) =>
+    Effect.gen(function* () {
+      yield* refuseLiteralSecrets(news.headers);
+      const objectId = output?.id ?? (yield* physicalIdOf(id, instanceId));
+      const rows = yield* listPassThroughEndpoints();
+      const { conflict, mine } = locate(rows, objectId, news.path);
+
+      if (mine === undefined) {
+        // ⚠️ A CONFLICT HERE — reconcile, not read — means ownership shifted between plan and
+        //   apply (a config row or a foreign DB row landed on this path after `read` cleared it).
+        //   `read` gates a genuine adopt by returning `Unowned`; reconcile itself never adopts,
+        //   so ANY conflict here fails rather than risking a second row on one path.
+        if (conflict !== undefined) return yield* Effect.fail(conflictRefusal(conflict, news.path));
+        yield* createPassThroughEndpoint(createBody(news, objectId));
+      } else if (mine.is_from_config === true) {
+        // ⛔ NEVER UPDATE OR DELETE AN `is_from_config` ROW, even one this resource's own
+        //   deterministic id happens to match (a config.yaml author could in principle choose the
+        //   same id `createPhysicalName` would). Refuse rather than silently editing the file's row.
+        return yield* Effect.fail(new LitellmConfigPathConflictError({ path: news.path }));
+      } else if (needsReplace(toAttributes(mine, objectId), news)) {
+        yield* deletePassThroughEndpoint(objectId);
+        yield* createPassThroughEndpoint(createBody(news, objectId));
+      } else if (!matches(toAttributes(mine, objectId), news)) {
+        const body = updateBody(news);
+        if (Object.keys(body).length > 0) yield* updatePassThroughEndpoint(objectId, body);
+      }
+
+      const after = (yield* listPassThroughEndpoints()).find((row) => row.id === objectId);
+      if (after === undefined) {
+        return yield* Effect.die(
+          new Error(
+            `LiteLLM.PassThroughEndpoint ${news.path}: the write returned no error but id ` +
+              `${objectId} is still absent from GET /config/pass_through_endpoint — read back ` +
+              'rather than trusting the call that just returned.',
+          ),
+        );
+      }
+      return toAttributes(after, objectId);
+    }),
+
+  delete: ({
+    id,
+    instanceId,
+    olds,
+    output,
+  }: {
+    id: string;
+    instanceId: string;
+    olds: PassThroughEndpointProps;
+    output: PassThroughEndpointAttributes;
+  }) =>
+    Effect.gen(function* () {
+      const objectId = output.id ?? (yield* physicalIdOf(id, instanceId));
+      const rows = yield* listPassThroughEndpoints();
+      const live = rows.find((row) => row.id === objectId);
+      // ⛔ NEVER DELETE AN `is_from_config` ROW, and a DB row this resource never created (a path
+      //   match with a different id) is not this resource's to remove either.
+      if (live === undefined || live.is_from_config === true || live.path !== olds.path) return;
+      yield* deletePassThroughEndpoint(objectId);
+    }),
+
+  list: () => Effect.succeed([]),
+};
+
+export const LiteLLMPassThroughEndpointProvider = () =>
+  Provider.effect(
+    LiteLLMPassThroughEndpoint,
+    Effect.succeed(LiteLLMPassThroughEndpoint.Provider.of(passThroughHandlers)),
+  );

package/src/litellm/pass-through-form.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  createBody,
+  literalSecretHeaders,
+  matches,
+  needsReplace,
+  updateBody,
+} from './pass-through-form.ts';
+
+const PROPS = { path: '/bria', target: 'https://api.bria.ai' };
+
+describe('createBody', () => {
+  test('settles the vendor defaults and never sends undefined keys', () => {
+    const body = createBody(PROPS, 'ep-1');
+    expect(body).toEqual({
+      auth: true,
+      cost_per_request: 0,
+      default_query_params: {},
+      headers: {},
+      id: 'ep-1',
+      include_subpath: false,
+      path: '/bria',
+      target: 'https://api.bria.ai',
+    });
+    expect('timeout' in body).toBe(false);
+    expect('methods' in body).toBe(false);
+    expect('guardrails' in body).toBe(false);
+  });
+
+  test('carries a declared nullable field through', () => {
+    const body = createBody({ ...PROPS, timeout: 30, methods: ['GET'] }, 'ep-1');
+    expect(body.timeout).toBe(30);
+    expect(body.methods).toEqual(['GET']);
+  });
+});
+
+describe('updateBody', () => {
+  /** ⛔ `exclude_none` can never clear a field through this call — needsReplace exists for that. */
+  test('omits an unset nullable field rather than sending it as null', () => {
+    const body = updateBody(PROPS);
+    expect('timeout' in body).toBe(false);
+    expect('guardrails' in body).toBe(false);
+  });
+
+  test('carries a declared value through', () => {
+    expect(updateBody({ ...PROPS, timeout: 5 }).timeout).toBe(5);
+  });
+});
+
+describe('needsReplace', () => {
+  const live = (over: Partial<Parameters<typeof needsReplace>[0]>) => ({
+    auth: true,
+    cost_per_request: 0,
+    default_query_params: {},
+    headers: {},
+    id: 'ep-1',
+    include_subpath: false,
+    path: '/bria',
+    target: 'https://api.bria.ai',
+    ...over,
+  });
+
+  test('timeout going from set to unset forces a replace', () => {
+    expect(needsReplace(live({ timeout: 30 }), PROPS)).toBe(true);
+  });
+
+  test('timeout staying unset, or staying set, is not a replace', () => {
+    expect(needsReplace(live({}), PROPS)).toBe(false);
+    expect(needsReplace(live({ timeout: 30 }), { ...PROPS, timeout: 60 })).toBe(false);
+  });
+
+  test('methods and guardrails going from set to unset also force a replace', () => {
+    expect(needsReplace(live({ methods: ['GET'] }), PROPS)).toBe(true);
+    expect(needsReplace(live({ guardrails: { pii: null } }), PROPS)).toBe(true);
+  });
+});
+
+describe('matches', () => {
+  const live = {
+    auth: true,
+    cost_per_request: 0,
+    default_query_params: {},
+    headers: {},
+    id: 'ep-1',
+    include_subpath: false,
+    path: '/bria',
+    target: 'https://api.bria.ai',
+  };
+
+  test('a settled default matches a declaration that omits the field', () => {
+    expect(matches(live, PROPS)).toBe(true);
+  });
+
+  test('a changed target does not match', () => {
+    expect(matches(live, { ...PROPS, target: 'https://elsewhere.example.com' })).toBe(false);
+  });
+
+  test('header order does not matter, header content does', () => {
+    expect(
+      matches({ ...live, headers: { a: '1', b: '2' } }, { ...PROPS, headers: { b: '2', a: '1' } }),
+    ).toBe(true);
+    expect(matches({ ...live, headers: { a: '1' } }, { ...PROPS, headers: { a: '2' } })).toBe(
+      false,
+    );
+  });
+});
+
+describe('literalSecretHeaders', () => {
+  test('an Authorization header without os.environ/ is refused', () => {
+    expect(literalSecretHeaders({ Authorization: 'Bearer sk-live-abc123' })).toEqual([
+      'Authorization',
+    ]);
+  });
+
+  test('the os.environ/ reference form is accepted', () => {
+    expect(literalSecretHeaders({ Authorization: 'os.environ/UPSTREAM_KEY' })).toEqual([]);
+  });
+
+  test('is case-insensitive on the header name and checks every secret-shaped name', () => {
+    expect(
+      literalSecretHeaders({ 'X-API-Key': 'literal', 'cf-aig-authorization': 'also-literal' }),
+    ).toEqual(['X-API-Key', 'cf-aig-authorization']);
+  });
+
+  test('an ordinary forwarded header is never flagged', () => {
+    expect(literalSecretHeaders({ 'X-Client-Version': '1.2.3' })).toEqual([]);
+  });
+});