@kutur-kit/assets 0.0.0-stage → 0.1.0-alpha.1

package/src/testing/AssetBucketContract.ts

@@ -0,0 +1,215 @@
+import { ByteSize, Effect, Option, Result, Schema, Stream } from "effect";
+
+import * as AssetBucket from "../AssetBucket.ts";
+
+/** The bucket the cases use. Back it with the implementation under test. */
+export class ContractBucket extends AssetBucket.Service<ContractBucket>()("assets-contract") {}
+
+/**
+ * Checks an `AssetBucket.Bucket` implementation against the guarantees it
+ * documents. Cases overwrite or delete the keys they use, under `contract/`.
+ * Run each case with any test runner.
+ */
+export interface Case {
+  readonly name: string;
+  readonly run: Effect.Effect<void, never, ContractBucket>;
+}
+
+const text = (value: string) => new TextEncoder().encode(value);
+
+const put = (
+  key: string,
+  chunks: ReadonlyArray<string>,
+  contentType = "text/plain",
+  cacheControl?: string,
+) =>
+  Effect.flatMap(ContractBucket, (bucket) =>
+    bucket.put({ key, contentType, cacheControl, body: Stream.fromIterable(chunks.map(text)) }),
+  );
+
+// The stored body as text, or null when the object is missing.
+const read = (key: string) =>
+  Effect.flatMap(ContractBucket, (bucket) => bucket.get(key)).pipe(
+    Effect.flatMap(
+      Option.match({
+        onNone: () => Effect.succeed(null),
+        onSome: ({ body }) =>
+          Stream.runCollect(body).pipe(
+            Effect.map((chunks) => chunks.map((chunk) => new TextDecoder().decode(chunk)).join("")),
+          ),
+      }),
+    ),
+  );
+
+const head = (key: string) => Effect.flatMap(ContractBucket, (bucket) => bucket.head(key));
+
+const remove = (key: string) => Effect.flatMap(ContractBucket, (bucket) => bucket.delete(key));
+
+const expectEqual = <A>(label: string, expected: A, received: A) => {
+  const [want, got] = [expected, received].map((value) => JSON.stringify(value));
+
+  return want === got
+    ? Effect.void
+    : Effect.die(
+        new Error(`AssetBucket contract violated: ${label}\nexpected: ${want}\nreceived: ${got}`),
+      );
+};
+
+const expectBody = (key: string, expected: string | null) =>
+  Effect.flatMap(read(key), (body) => expectEqual(`body of ${key}`, expected, body));
+
+// Encoding checks that sizes are ByteSize values and drops fields stores may add.
+const encodeInfo = Schema.encodeEffect(
+  Schema.toCodecJson(
+    Schema.NullOr(
+      Schema.Struct({
+        size: Schema.ByteSize,
+        contentType: Schema.String,
+        cacheControl: Schema.optionalKey(Schema.String),
+      }),
+    ),
+  ),
+);
+
+// No cache control compares equal whether a store omits it or sets it to undefined.
+const comparable = (info: AssetBucket.Info | null) => {
+  if (info === null) return null;
+
+  const { size, contentType, cacheControl } = info;
+
+  return cacheControl === undefined ? { size, contentType } : { size, contentType, cacheControl };
+};
+
+const expectInfo = (
+  label: string,
+  expected: AssetBucket.Info | null,
+  received: AssetBucket.Info | null,
+) =>
+  Effect.flatMap(
+    Effect.all([encodeInfo(comparable(expected)), encodeInfo(comparable(received))]),
+    ([want, got]) => expectEqual(label, want, got),
+  ).pipe(Effect.orDie);
+
+const expectHead = (key: string, expected: AssetBucket.Info | null) =>
+  Effect.flatMap(head(key), (info) =>
+    expectInfo(`head of ${key}`, expected, Option.getOrNull(info)),
+  );
+
+const stored = "contract/stored.txt";
+
+const nested = "contract/nested";
+
+const child = "contract/nested/child";
+
+export const cases: ReadonlyArray<Case> = [
+  {
+    name: "returns the stored bytes and info",
+    run: Effect.gen(function* () {
+      const info = yield* put(stored, ["hello, ", "", "wörld"], "text/plain; charset=utf-8");
+      const expected = { size: ByteSize.bytes(13), contentType: "text/plain; charset=utf-8" };
+      yield* expectInfo("put info", expected, info);
+      yield* expectHead(stored, expected);
+      yield* expectBody(stored, "hello, wörld");
+
+      const object = yield* Effect.flatMap(ContractBucket, (bucket) => bucket.get(stored));
+
+      yield* expectInfo(
+        `get info of ${stored}`,
+        expected,
+        Option.getOrNull(Option.map(object, ({ info }) => info)),
+      );
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "stores empty objects",
+    run: Effect.gen(function* () {
+      yield* put(stored, [], "application/octet-stream");
+      yield* expectHead(stored, { size: ByteSize.zero, contentType: "application/octet-stream" });
+      yield* expectBody(stored, "");
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "replaces an object on put",
+    run: Effect.gen(function* () {
+      yield* put(stored, ["first version"]);
+      yield* put(stored, ["second"], "text/markdown");
+      yield* expectHead(stored, { size: ByteSize.bytes(6), contentType: "text/markdown" });
+      yield* expectBody(stored, "second");
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "stores the cache control an object is served with, and replaces it on put",
+    run: Effect.gen(function* () {
+      const immutable = "public, max-age=31536000, immutable";
+      const info = yield* put(stored, ["cached"], "text/plain", immutable);
+
+      const expected = {
+        size: ByteSize.bytes(6),
+        contentType: "text/plain",
+        cacheControl: immutable,
+      };
+
+      yield* expectInfo("put info", expected, info);
+      yield* expectHead(stored, expected);
+
+      const object = yield* Effect.flatMap(ContractBucket, (bucket) => bucket.get(stored));
+
+      yield* expectInfo(
+        `get info of ${stored}`,
+        expected,
+        Option.getOrNull(Option.map(object, ({ info }) => info)),
+      );
+
+      yield* put(stored, ["uncached"]);
+      yield* expectHead(stored, { size: ByteSize.bytes(8), contentType: "text/plain" });
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "keeps a key and the keys nested under it apart",
+    run: Effect.gen(function* () {
+      yield* put(nested, ["parent"]);
+      yield* put(child, ["child"]);
+      yield* remove(child);
+      yield* expectBody(nested, "parent");
+      yield* expectBody(child, null);
+      yield* put(child, ["child"]);
+      yield* remove(nested);
+      yield* expectBody(child, "child");
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "reports missing objects and deletes them more than once",
+    run: Effect.gen(function* () {
+      yield* put(stored, ["to delete"]);
+      yield* remove(stored);
+      yield* expectHead(stored, null);
+      yield* expectBody(stored, null);
+      yield* remove(stored);
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "keeps the previous object when a body fails",
+    run: Effect.gen(function* () {
+      yield* put(stored, ["previous"]);
+
+      const failing = Stream.concat(
+        Stream.make(text("partial")),
+        Stream.fail("body failed" as const),
+      );
+
+      const bucket = yield* ContractBucket;
+
+      const result = yield* Effect.result(
+        bucket.put({ key: stored, contentType: "text/plain", body: failing }),
+      );
+
+      yield* expectEqual(
+        "error of a put whose body failed",
+        "body failed",
+        Result.isFailure(result) ? result.failure : "success",
+      );
+      yield* expectHead(stored, { size: ByteSize.bytes(8), contentType: "text/plain" });
+      yield* expectBody(stored, "previous");
+    }).pipe(Effect.orDie),
+  },
+];

package/src/testing/AssetSigningContract.ts

@@ -0,0 +1,254 @@
+import { ByteSize, Duration, Effect, Option } from "effect";
+import { HttpClient, HttpClientRequest } from "effect/http";
+
+import * as AssetSigning from "../AssetSigning.ts";
+import { ContractBucket } from "./AssetBucketContract.ts";
+
+/**
+ * Checks a `Signing` implementation and the storage it signs for, over HTTP:
+ * signed requests succeed, and requests that differ from what was signed are
+ * refused without changing what is stored, and a signed upload writes once. Provide the `ContractBucket`, its
+ * `Signing` and an `HttpClient` that can reach the signed URLs. Expiry is not
+ * checked: it depends on the storage's clock. Cases delete the keys they
+ * use under `contract/` first, so storage may keep objects between cases.
+ */
+export interface Case {
+  readonly name: string;
+  readonly run: Effect.Effect<
+    void,
+    never,
+    ContractBucket | AssetSigning.SigningOf<ContractBucket> | HttpClient.HttpClient
+  >;
+}
+
+const signing = AssetSigning.of(ContractBucket);
+
+const key = "contract/signed.png";
+
+const expiresIn = Duration.minutes(5);
+
+const png = new Uint8Array([0x89, 0x50, 0x4e, 0x47]);
+
+// Not `no-cache`, which clients add to conditional requests themselves.
+const cacheControl = "public, max-age=60";
+
+const violated = (message: string) =>
+  Effect.die(new Error(`AssetSigning contract violated: ${message}`));
+
+const ensure = (holds: boolean, message: string) => (holds ? Effect.void : violated(message));
+
+const ok = (status: number) => status >= 200 && status < 300;
+
+const signPut = (contentType = "image/png", contentLength = png.length) =>
+  Effect.flatMap(signing, (signer) =>
+    signer.signPut({
+      key,
+      contentType,
+      contentLength: ByteSize.bytes(contentLength),
+      cacheControl,
+      expiresIn,
+    }),
+  );
+
+/** Sends a signed request as a client would, with its headers and a body. */
+const send = (
+  signed: AssetSigning.SignedRequest,
+  options: {
+    readonly body?: Uint8Array;
+    readonly headers?: Record<string, string>;
+    readonly url?: string;
+  } = {},
+) =>
+  HttpClient.execute(
+    HttpClientRequest.make(signed.method)(options.url ?? signed.url).pipe(
+      HttpClientRequest.setHeaders({ ...signed.headers, ...options.headers }),
+      (request) =>
+        options.body === undefined
+          ? request
+          : HttpClientRequest.bodyUint8Array(
+              request,
+              options.body,
+              options.headers?.["content-type"] ?? signed.headers["content-type"],
+            ),
+    ),
+  );
+
+// The value of the URL's signature parameter, such as S3's `X-Amz-Signature`.
+const signatureOf = (url: string) =>
+  [...new URL(url, "http://localhost").searchParams].find(([name]) =>
+    /signature$/iu.test(name),
+  )?.[1] ?? "";
+
+// Cases start without the objects they check for.
+const clear = Effect.flatMap(ContractBucket, (bucket) =>
+  Effect.andThen(bucket.delete(key), bucket.delete("contract/other.png")),
+);
+
+const stored = Effect.flatMap(ContractBucket, (bucket) => bucket.head(key));
+
+const expectRefused = (label: string, response: { readonly status: number }) =>
+  ok(response.status)
+    ? violated(`${label} was accepted with ${response.status}`)
+    : Effect.flatMap(stored, (info) =>
+        Option.isSome(info) ? violated(`${label} stored an object`) : Effect.void,
+      );
+
+export const cases: ReadonlyArray<Case> = [
+  {
+    name: "stores a signed upload and serves it to a signed download",
+    run: Effect.gen(function* () {
+      yield* clear;
+
+      const put = yield* signPut();
+      const uploaded = yield* send(put, { body: png });
+
+      yield* ensure(ok(uploaded.status), `a signed upload failed with ${uploaded.status}`);
+
+      const info = yield* stored;
+
+      yield* ensure(
+        Option.isSome(info) &&
+          info.value.contentType === "image/png" &&
+          info.value.cacheControl === cacheControl,
+        "a signed upload was not stored with its content type and cache control",
+      );
+
+      const get = yield* Effect.flatMap(signing, (signer) => signer.signGet({ key, expiresIn }));
+      const downloaded = yield* send(get);
+      const body = new Uint8Array(yield* downloaded.arrayBuffer);
+
+      yield* ensure(
+        downloaded.status === 200 && body.join() === png.join(),
+        "a signed download did not return the upload",
+      );
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "signs uploads with no headers but `uploadHeaders`, which CORS rules allow",
+    run: Effect.gen(function* () {
+      const put = yield* signPut();
+      const allowed: ReadonlySet<string> = new Set(AssetSigning.uploadHeaders);
+      const others = Object.keys(put.headers).filter((name) => !allowed.has(name));
+
+      yield* ensure(
+        others.length === 0,
+        `a signed upload needs other headers: ${others.join(", ")}`,
+      );
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "refuses an upload of another content type than signed",
+    run: Effect.gen(function* () {
+      yield* clear;
+
+      const put = yield* signPut("image/png");
+
+      yield* expectRefused(
+        "an upload as text/html",
+        yield* send(put, { body: png, headers: { "content-type": "text/html" } }),
+      );
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "refuses an upload with another cache control than signed",
+    run: Effect.gen(function* () {
+      yield* clear;
+
+      const put = yield* signPut();
+
+      yield* expectRefused(
+        "an upload cached for a year",
+        yield* send(put, {
+          body: png,
+          headers: { "cache-control": "public, max-age=31536000, immutable" },
+        }),
+      );
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "refuses an upload of another length than signed",
+    run: Effect.gen(function* () {
+      yield* clear;
+
+      const put = yield* signPut("image/png", png.length);
+
+      yield* expectRefused(
+        "a longer upload",
+        yield* send(put, { body: new Uint8Array([...png, 0]) }),
+      );
+      yield* expectRefused("a shorter upload", yield* send(put, { body: png.slice(1) }));
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "refuses a signed URL used for another key or with its signature changed",
+    run: Effect.gen(function* () {
+      yield* clear;
+
+      const put = yield* signPut();
+      const signature = signatureOf(put.url);
+
+      yield* ensure(signature !== "", "a signed URL has no signature parameter");
+
+      const flipped = `${signature.slice(0, -1)}${signature.endsWith("0") ? "1" : "0"}`;
+
+      yield* expectRefused(
+        "an upload to another key",
+        yield* send(put, { body: png, url: put.url.replace("signed.png", "other.png") }),
+      );
+      yield* expectRefused(
+        "an upload with a changed signature",
+        yield* send(put, { body: png, url: put.url.replace(signature, flipped) }),
+      );
+
+      const other = yield* Effect.flatMap(ContractBucket, (bucket) =>
+        bucket.head("contract/other.png"),
+      );
+
+      yield* ensure(Option.isNone(other), "an upload to another key was stored");
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "writes a signed upload once, however its URL is replayed",
+    run: Effect.gen(function* () {
+      yield* clear;
+
+      const put = yield* signPut();
+
+      yield* send(put, { body: png });
+
+      // Same length and type, so only the write-once condition stops it.
+      const other = png.map((byte) => 255 - byte);
+
+      const { "if-none-match": _, ...unconditional } = put.headers;
+
+      const replays = [
+        yield* send(put, { body: other }),
+        yield* send({ ...put, headers: unconditional }, { body: other }),
+      ];
+
+      yield* ensure(
+        replays.every((response) => !ok(response.status)),
+        `a replayed upload was accepted with ${replays.map((response) => response.status).join(", ")}`,
+      );
+
+      const get = yield* Effect.flatMap(signing, (signer) => signer.signGet({ key, expiresIn }));
+      const body = new Uint8Array(yield* (yield* send(get)).arrayBuffer);
+
+      yield* ensure(body.join() === png.join(), "a replayed upload replaced the object");
+    }).pipe(Effect.orDie),
+  },
+  {
+    name: "refuses a signed upload URL used to download",
+    run: Effect.gen(function* () {
+      yield* clear;
+
+      const put = yield* signPut();
+
+      yield* send(put, { body: png });
+
+      const downloaded = yield* send({ ...put, method: "GET" });
+
+      yield* ensure(!ok(downloaded.status), "an upload URL served a download");
+    }).pipe(Effect.orDie),
+  },
+];

package/src/testing/index.ts

@@ -0,0 +1,3 @@
+export * as AssetBucketContract from "./AssetBucketContract.ts";
+
+export * as AssetSigningContract from "./AssetSigningContract.ts";