Cover wire shape, auth, batchSize, Retry-After dates, override and timeout

Author: TheGreatAxios

IMPLEMENTATION.md

@@ -108,6 +108,7 @@ package depends only on the published surface).
 - `tests/retry.test.ts` — 429 retried once after `Retry-After` on the
   harness clock; 401 rejects without retry.
 - `tests/base64.test.ts` — `base64` and `float` agree over a real HTTP stub.
-- `tests/live.test.ts` — round trip against a real `/v1/embeddings`
-  (`EMBEDDING_E2E_BASE_URL`, default local Ollama; `EMBEDDING_E2E_MODEL`,
-  default `nomic-embed-text`). Skips when unreachable.
+- `live/embeddings.test.ts` (`bun run test:live`, not in `test` or CI) —
+  round trip against a real `/v1/embeddings` (`EMBEDDING_E2E_BASE_URL`,
+  required; `EMBEDDING_E2E_MODEL`, default `nomic-embed-text`).
+  Skips when unset or unreachable.

tests/live.test.ts live/embeddings.test.tstests/live.test.ts renamed to live/embeddings.test.ts

@@ -2,19 +2,21 @@ import { describe, expect, test } from "bun:test";
 
 import { embedTexts, probeEmbedDims } from "../src/index";
 
-// Any OpenAI-compatible `/v1/embeddings` server; defaults to local Ollama.
-const config = {
-  baseURL: process.env.EMBEDDING_E2E_BASE_URL ?? "http://localhost:11434/v1",
-  model: process.env.EMBEDDING_E2E_MODEL ?? "nomic-embed-text",
-};
+// Any OpenAI-compatible `/v1/embeddings` server. Skips unless
+// EMBEDDING_E2E_BASE_URL is set, so it never loads a model on this machine.
+const baseURL = process.env.EMBEDDING_E2E_BASE_URL;
+const model = process.env.EMBEDDING_E2E_MODEL ?? "nomic-embed-text";
 
 // Skips unless the server answers and lists the model.
-const reachable = await fetch(`${config.baseURL}/models`, {
-  signal: AbortSignal.timeout(1_000),
-}).then(
-  async (res) => res.ok && (await res.text()).includes(`"${config.model}`),
-  () => false,
-);
+const reachable =
+  baseURL !== undefined &&
+  (await fetch(`${baseURL}/models`, {
+    signal: AbortSignal.timeout(1_000),
+  }).then(
+    async (res) => res.ok && (await res.text()).includes(`"${model}`),
+    () => false,
+  ));
+const config = { baseURL: baseURL ?? "", model };
 
 function cosine(a: number[], b: number[]): number {
   let dot = 0;

package.json

@@ -18,6 +18,7 @@
     "prepack": "bun run build",
     "typecheck": "tsc --noEmit",
     "test": "bun test ./src ./tests",
+    "test:live": "bun test ./live",
     "format": "prettier -w ."
   },
   "dependencies": {

src/embed.test.ts

@@ -87,6 +87,10 @@ test("rejects duplicate indices and undecodable base64", async () => {
     ],
     [
       { index: 0, embedding: "!!!notbase64" },
+      { index: 1, embedding: "AAAAAA==" },
+    ],
+    [
+      { index: 0, embedding: "AAAAAA==" },
       { index: 1, embedding: "AAA=" },
     ],
   ]) {
@@ -111,3 +115,56 @@ test("classifies a 200 that is not JSON instead of leaking a SyntaxError", async
     reason: { category: "protocol_mismatch" },
   });
 });
+
+test("sends only configured fields to {baseURL}/embeddings", async () => {
+  harness = setupHarness();
+  const stream = harness.scenario.createStream();
+  harness.scenario.whenRequestBodyMatches(
+    (body, req) =>
+      req.url === "https://embed.example/v1/embeddings" &&
+      !req.headers.has("authorization") &&
+      body === JSON.stringify({ model: CONFIG.model, input: ["a"] }),
+    stream,
+  );
+  stream.enqueueAll(
+    [new TextEncoder().encode('{"data":[{"index":0,"embedding":[1]}]}')],
+    { startAt: 1 },
+  );
+  const pending = embedTexts(["a"], CONFIG, { deps: harness.deps });
+  expect(await run(harness, pending)).toEqual([[1]]);
+});
+
+test("sends a bearer token only when apiKey is set", async () => {
+  harness = setupHarness();
+  const stream = harness.scenario.createStream();
+  harness.scenario.whenRequestMatches(
+    (req) => req.headers.get("authorization") === "Bearer sk-test",
+    stream,
+  );
+  stream.enqueueAll(
+    [new TextEncoder().encode('{"data":[{"index":0,"embedding":[1]}]}')],
+    { startAt: 1 },
+  );
+  const pending = embedTexts(
+    ["a"],
+    { ...CONFIG, apiKey: "sk-test" },
+    { deps: harness.deps },
+  );
+  expect(await run(harness, pending)).toEqual([[1]]);
+});
+
+test("returns [] for empty input without a request", async () => {
+  harness = setupHarness();
+  const pending = embedTexts([], CONFIG, { deps: harness.deps });
+  expect(await run(harness, pending)).toEqual([]);
+});
+
+test("rejects a non-positive batchSize before any request", async () => {
+  harness = setupHarness();
+  for (const batchSize of [0, -1, 1.5]) {
+    await expect(
+      embedTexts(["a"], { ...CONFIG, batchSize }, { deps: harness.deps }),
+    ).rejects.toThrow(/batchSize/);
+  }
+  await harness.run();
+});

tests/retry.test.ts

@@ -53,3 +53,59 @@ test("rejects a 401 without retrying", async () => {
     reason: { category: "credential_failure", statusCode: 401 },
   });
 });
+
+test("waits until an HTTP-date Retry-After", async () => {
+  harness = setupHarness({ enableInferenceTimers: true });
+  const at = new Date(Date.now() + 20_000).toUTCString();
+  reply(harness, "rate limited", 429, { "retry-after": at });
+  reply(harness, JSON.stringify({ data: [{ index: 0, embedding: [1] }] }), 200);
+
+  const pending = embedTexts(["a"], CONFIG, { deps: harness.deps });
+  await harness.run();
+
+  expect(await pending).toEqual([[1]]);
+  expect(harness.clock.now()).toBeGreaterThanOrEqual(19_000);
+});
+
+test("treats a past HTTP-date Retry-After as no wait", async () => {
+  harness = setupHarness({ enableInferenceTimers: true });
+  const at = new Date(Date.now() - 60_000).toUTCString();
+  reply(harness, "rate limited", 429, { "retry-after": at });
+  reply(harness, JSON.stringify({ data: [{ index: 0, embedding: [1] }] }), 200);
+
+  const pending = embedTexts(["a"], CONFIG, { deps: harness.deps });
+  await harness.run();
+
+  expect(await pending).toEqual([[1]]);
+  expect(harness.clock.now()).toBeLessThan(1_000);
+});
+
+test("honors a caller-supplied extractRetryAfterMs", async () => {
+  harness = setupHarness({ enableInferenceTimers: true });
+  reply(harness, "rate limited", 429);
+  reply(harness, JSON.stringify({ data: [{ index: 0, embedding: [1] }] }), 200);
+
+  const pending = embedTexts(["a"], CONFIG, {
+    deps: harness.deps,
+    extractRetryAfterMs: () => 45_000,
+  });
+  await harness.run();
+
+  expect(await pending).toEqual([[1]]);
+  expect(harness.clock.now()).toBeGreaterThanOrEqual(45_000);
+});
+
+test("applies timeoutMs even when the caller passes a signal", async () => {
+  harness = setupHarness();
+  const stream = harness.scenario.createStream();
+  harness.scenario.whenRequestMatches(() => true, stream);
+
+  const pending = embedTexts(
+    ["a"],
+    { ...CONFIG, timeoutMs: 50 },
+    { deps: harness.deps, signal: new AbortController().signal },
+  );
+  await harness.run();
+
+  await expect(pending).rejects.toBeInstanceOf(EmbeddingRequestError);
+});

tsconfig.json

@@ -25,5 +25,5 @@
 
     "lib": ["ESNext"]
   },
-  "include": ["src/**/*.ts", "tests/**/*.ts"]
+  "include": ["src/**/*.ts", "tests/**/*.ts", "live/**/*.ts"]
 }