@kensio/yulin 1.20.17 → 1.21.1

package/dist/service/s3/bucket/versioning/sim-s3-bucket-versions.d.ts

@@ -0,0 +1,97 @@
+import type { SimS3Object } from "../../object/s3-object.js";
+import type { SimS3BucketStorage } from "../../storage/s3-bucket-storage.js";
+import { SimS3BucketVersioning } from "./sim-s3-bucket-versioning.js";
+import { SimS3ObjectVersion } from "./sim-s3-object-version.js";
+/**
+ * The versioning of one simulated S3 Bucket, and the versions it has kept.
+ *
+ * Storage holds the current Object under each key and nothing else, which is
+ * what lets every reader of a Bucket carry on unchanged. The version history
+ * holds every version including that current one, and the two are kept in step
+ * here: writing a delete marker takes the Object out of storage, and deleting
+ * a version puts back whatever the removal left current.
+ */
+export declare class SimS3BucketVersions {
+    private versioning;
+    private readonly history;
+    /**
+     * How this Bucket is configured.
+     */
+    get configuration(): SimS3BucketVersioning;
+    /**
+     * Whether this Bucket holds a version history.
+     */
+    get keepsVersions(): boolean;
+    /**
+     * Apply a versioning configuration to this Bucket.
+     *
+     * Enabling versioning over a Bucket that already holds Objects gives each of
+     * them the null version id, which is what real S3 does with the Objects
+     * written before the configuration arrived. They become the current version
+     * of their key and stay readable by that id afterwards.
+     */
+    configure(versioning: SimS3BucketVersioning, stored: readonly SimS3Object[]): void;
+    /**
+     * Record a write, answering the version it was given.
+     *
+     * A Bucket with versioning enabled gets a new id every time. A suspended one
+     * writes over the null version, because real S3 holds one Object under that
+     * id rather than a run of them. A Bucket nobody has configured records
+     * nothing at all.
+     */
+    recordPut(object: SimS3Object): SimS3ObjectVersion | undefined;
+    /**
+     * Write a delete marker over a key and take the Object out of storage.
+     *
+     * Real S3 writes the marker whether or not the key held anything, so a
+     * delete of a key that was never written still leaves one behind.
+     */
+    markDeleted(storage: SimS3BucketStorage, key: string, at: Date): Promise<SimS3ObjectVersion>;
+    /**
+     * Remove one version permanently, answering the version that went.
+     *
+     * Whatever the removal leaves at the head of the key becomes current, so
+     * deleting a delete marker brings the Object under it back and deleting the
+     * current Object exposes the one written before it.
+     */
+    deleteVersion(storage: SimS3BucketStorage, key: string, versionId: string): Promise<SimS3ObjectVersion | undefined>;
+    /**
+     * One version of one key, by the id it was given.
+     */
+    find(key: string, versionId: string): SimS3ObjectVersion | undefined;
+    /**
+     * The version a read of this key without a version id answers with.
+     */
+    current(key: string): SimS3ObjectVersion | undefined;
+    /**
+     * Take a version a lifecycle rule expired out of the history.
+     *
+     * Storage is left alone, unlike `deleteVersion`. A rule for noncurrent
+     * versions never reaches the current one, and a delete marker holds no
+     * bytes, so nothing this removes was in storage to begin with.
+     */
+    removeExpired(key: string, versionId: string): void;
+    /**
+     * Every version this Bucket holds, in the order a listing reports them.
+     */
+    list(prefix?: string): readonly SimS3ObjectVersion[];
+    /**
+     * Remove the null version from a Bucket that keeps no history.
+     *
+     * Real S3 gives every Object in such a Bucket the null version id, so a
+     * delete naming that id removes the Object rather than doing nothing. Any
+     * other id names a version the Bucket never issued.
+     */
+    private removeNullVersion;
+    /**
+     * Make storage hold whatever is now current under a key.
+     */
+    private restoreCurrent;
+    /**
+     * The id the next version of anything gets.
+     *
+     * Real S3 version ids are opaque, and a suspended Bucket writes under the
+     * null id rather than minting one.
+     */
+    private nextVersionId;
+}

package/dist/service/s3/bucket/versioning/sim-s3-bucket-versions.js

@@ -0,0 +1,176 @@
+import { randomUUID } from "node:crypto";
+import { SimS3BucketVersioning, simS3NullVersionId, } from "./sim-s3-bucket-versioning.js";
+import { SimS3ObjectVersion } from "./sim-s3-object-version.js";
+import { SimS3ObjectVersions } from "./sim-s3-object-versions.js";
+/**
+ * The versioning of one simulated S3 Bucket, and the versions it has kept.
+ *
+ * Storage holds the current Object under each key and nothing else, which is
+ * what lets every reader of a Bucket carry on unchanged. The version history
+ * holds every version including that current one, and the two are kept in step
+ * here: writing a delete marker takes the Object out of storage, and deleting
+ * a version puts back whatever the removal left current.
+ */
+export class SimS3BucketVersions {
+    versioning = SimS3BucketVersioning.unversioned();
+    history = new SimS3ObjectVersions();
+    /**
+     * How this Bucket is configured.
+     */
+    get configuration() {
+        return this.versioning;
+    }
+    /**
+     * Whether this Bucket holds a version history.
+     */
+    get keepsVersions() {
+        return this.versioning.keepsVersions;
+    }
+    /**
+     * Apply a versioning configuration to this Bucket.
+     *
+     * Enabling versioning over a Bucket that already holds Objects gives each of
+     * them the null version id, which is what real S3 does with the Objects
+     * written before the configuration arrived. They become the current version
+     * of their key and stay readable by that id afterwards.
+     */
+    configure(versioning, stored) {
+        const seeding = !this.versioning.keepsVersions && versioning.keepsVersions;
+        this.versioning = versioning;
+        if (!seeding) {
+            return;
+        }
+        for (const object of stored) {
+            this.history.add(SimS3ObjectVersion.nullVersionOf(object));
+        }
+    }
+    /**
+     * Record a write, answering the version it was given.
+     *
+     * A Bucket with versioning enabled gets a new id every time. A suspended one
+     * writes over the null version, because real S3 holds one Object under that
+     * id rather than a run of them. A Bucket nobody has configured records
+     * nothing at all.
+     */
+    recordPut(object) {
+        if (!this.versioning.keepsVersions) {
+            return undefined;
+        }
+        const version = new SimS3ObjectVersion({
+            versionId: this.nextVersionId(),
+            key: object.key,
+            createdAt: object.lastModified,
+            object,
+        });
+        if (this.versioning.isEnabled) {
+            this.history.add(version);
+        }
+        else {
+            this.history.replace(version);
+        }
+        return version;
+    }
+    /**
+     * Write a delete marker over a key and take the Object out of storage.
+     *
+     * Real S3 writes the marker whether or not the key held anything, so a
+     * delete of a key that was never written still leaves one behind.
+     */
+    async markDeleted(storage, key, at) {
+        const marker = new SimS3ObjectVersion({
+            versionId: this.nextVersionId(),
+            key,
+            createdAt: at,
+        });
+        if (this.versioning.isEnabled) {
+            this.history.add(marker);
+        }
+        else {
+            this.history.replace(marker);
+        }
+        await storage.deleteObject(key);
+        return marker;
+    }
+    /**
+     * Remove one version permanently, answering the version that went.
+     *
+     * Whatever the removal leaves at the head of the key becomes current, so
+     * deleting a delete marker brings the Object under it back and deleting the
+     * current Object exposes the one written before it.
+     */
+    async deleteVersion(storage, key, versionId) {
+        if (!this.versioning.keepsVersions) {
+            return await this.removeNullVersion(storage, key, versionId);
+        }
+        const removed = this.history.remove(key, versionId);
+        if (removed !== undefined) {
+            await this.restoreCurrent(storage, key);
+        }
+        return removed;
+    }
+    /**
+     * One version of one key, by the id it was given.
+     */
+    find(key, versionId) {
+        return this.history.find(key, versionId);
+    }
+    /**
+     * The version a read of this key without a version id answers with.
+     */
+    current(key) {
+        return this.history.current(key);
+    }
+    /**
+     * Take a version a lifecycle rule expired out of the history.
+     *
+     * Storage is left alone, unlike `deleteVersion`. A rule for noncurrent
+     * versions never reaches the current one, and a delete marker holds no
+     * bytes, so nothing this removes was in storage to begin with.
+     */
+    removeExpired(key, versionId) {
+        this.history.remove(key, versionId);
+    }
+    /**
+     * Every version this Bucket holds, in the order a listing reports them.
+     */
+    list(prefix) {
+        return this.history.list(prefix);
+    }
+    /**
+     * Remove the null version from a Bucket that keeps no history.
+     *
+     * Real S3 gives every Object in such a Bucket the null version id, so a
+     * delete naming that id removes the Object rather than doing nothing. Any
+     * other id names a version the Bucket never issued.
+     */
+    async removeNullVersion(storage, key, versionId) {
+        const stored = versionId === simS3NullVersionId
+            ? await storage.getObject(key)
+            : undefined;
+        if (stored === undefined) {
+            return undefined;
+        }
+        await storage.deleteObject(key);
+        return SimS3ObjectVersion.nullVersionOf(stored);
+    }
+    /**
+     * Make storage hold whatever is now current under a key.
+     */
+    async restoreCurrent(storage, key) {
+        const current = this.history.current(key);
+        if (current === undefined || current.isDeleteMarker) {
+            await storage.deleteObject(key);
+            return;
+        }
+        await storage.putObject(current.object);
+    }
+    /**
+     * The id the next version of anything gets.
+     *
+     * Real S3 version ids are opaque, and a suspended Bucket writes under the
+     * null id rather than minting one.
+     */
+    nextVersionId() {
+        return this.versioning.isEnabled ? randomUUID() : simS3NullVersionId;
+    }
+}

package/dist/service/s3/bucket/versioning/sim-s3-compare-keys.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Order two Object keys the way S3 orders them.
+ *
+ * S3 orders keys by their UTF-8 bytes. Comparing the strings directly agrees
+ * with that for every key outside the supplementary planes, and `localeCompare`
+ * does not, because it collates by locale and can order the same two keys
+ * differently on two runtimes. `compareObjectKeys` in the Object listing
+ * compares the same way for the same reason.
+ */
+export declare function compareSimS3Keys(left: string, right: string): number;

package/dist/service/s3/bucket/versioning/sim-s3-compare-keys.js

@@ -0,0 +1,16 @@
+/**
+ * Order two Object keys the way S3 orders them.
+ *
+ * S3 orders keys by their UTF-8 bytes. Comparing the strings directly agrees
+ * with that for every key outside the supplementary planes, and `localeCompare`
+ * does not, because it collates by locale and can order the same two keys
+ * differently on two runtimes. `compareObjectKeys` in the Object listing
+ * compares the same way for the same reason.
+ */
+export function compareSimS3Keys(left, right) {
+    /* v8 ignore if -- a Bucket holds one Object per key, so no two keys are equal */
+    if (left === right) {
+        return 0;
+    }
+    return left < right ? -1 : 1;
+}

package/dist/service/s3/bucket/versioning/sim-s3-object-version.d.ts

@@ -0,0 +1,85 @@
+import { SimS3ObjectLock } from "../lock/sim-s3-object-lock.js";
+import type { SimS3Object } from "../../object/s3-object.js";
+interface SimS3ObjectVersionProperties {
+    readonly versionId: string;
+    readonly key: string;
+    readonly createdAt: Date;
+    /**
+     * The Object this version holds. A version without one is a delete marker,
+     * which records that the key was deleted and holds no bytes.
+     */
+    readonly object?: SimS3Object | undefined;
+}
+/**
+ * One version of one key in a simulated S3 Bucket.
+ *
+ * A version is either an Object or a delete marker, and both are versions in
+ * every other respect. Both carry an id, both appear in a listing, and both
+ * can be deleted by naming that id. Modelling the marker as a version without
+ * an Object keeps the ordering in one list, which is what decides which
+ * version is current.
+ */
+export declare class SimS3ObjectVersion {
+    readonly versionId: string;
+    readonly key: string;
+    /**
+     * What Object Lock holds against this version.
+     *
+     * Every version carries one, empty until something is put on it. A Bucket
+     * without Object Lock leaves every one of them empty, and an empty lock
+     * refuses nothing, so the delete path asks the same question either way.
+     */
+    readonly lock: SimS3ObjectLock;
+    private displaced;
+    private readonly createdAt;
+    private readonly stored;
+    constructor(properties: SimS3ObjectVersionProperties);
+    /**
+     * The version an Object in a Bucket that keeps none reads back under.
+     *
+     * Real S3 gives every Object in an unversioned Bucket the null version id,
+     * and answers ListObjectVersions for one as a history a single entry deep.
+     */
+    static nullVersionOf(object: SimS3Object): SimS3ObjectVersion;
+    /**
+     * Whether this version records a deletion instead of holding bytes.
+     */
+    get isDeleteMarker(): boolean;
+    /**
+     * The Object this version holds.
+     *
+     * A delete marker has none, and asking for one is a caller that skipped
+     * `isDeleteMarker`. Reporting that as an error beats handing back nothing,
+     * which reads as an empty Object further down.
+     */
+    get object(): SimS3Object;
+    /**
+     * When this version came into being, in simulated time.
+     *
+     * A copy, because a Date is mutable and every read of a version hands this
+     * one out.
+     */
+    get lastModified(): Date;
+    /**
+     * When this version stopped being the current one, if it has.
+     *
+     * A `NoncurrentVersionExpiration` counts from here rather than from the
+     * write, because a version written a year ago and displaced yesterday has
+     * been noncurrent for a day. Real S3 measures it the same way.
+     */
+    get noncurrentSince(): Date | undefined;
+    /**
+     * Record that a newer version has taken this one's place.
+     *
+     * Only the first displacement counts. Removing the version that displaced
+     * this one makes it current again, and a later write displaces it a second
+     * time, which real S3 measures from the later of the two.
+     */
+    displacedAt(instant: Date): void;
+    /**
+     * Record that this version is current again, which is what removing the
+     * version above it does.
+     */
+    restored(): void;
+}
+export {};

package/dist/service/s3/bucket/versioning/sim-s3-object-version.js

@@ -0,0 +1,101 @@
+import { assertDefined } from "../../../../util/type-guard/defined.js";
+import { SimS3ObjectLock } from "../lock/sim-s3-object-lock.js";
+import { simS3NullVersionId } from "./sim-s3-bucket-versioning.js";
+/**
+ * One version of one key in a simulated S3 Bucket.
+ *
+ * A version is either an Object or a delete marker, and both are versions in
+ * every other respect. Both carry an id, both appear in a listing, and both
+ * can be deleted by naming that id. Modelling the marker as a version without
+ * an Object keeps the ordering in one list, which is what decides which
+ * version is current.
+ */
+export class SimS3ObjectVersion {
+    versionId;
+    key;
+    /**
+     * What Object Lock holds against this version.
+     *
+     * Every version carries one, empty until something is put on it. A Bucket
+     * without Object Lock leaves every one of them empty, and an empty lock
+     * refuses nothing, so the delete path asks the same question either way.
+     */
+    lock = new SimS3ObjectLock();
+    displaced;
+    createdAt;
+    stored;
+    constructor(properties) {
+        this.versionId = properties.versionId;
+        this.key = properties.key;
+        this.createdAt = new Date(properties.createdAt);
+        this.stored = properties.object;
+    }
+    /**
+     * The version an Object in a Bucket that keeps none reads back under.
+     *
+     * Real S3 gives every Object in an unversioned Bucket the null version id,
+     * and answers ListObjectVersions for one as a history a single entry deep.
+     */
+    static nullVersionOf(object) {
+        return new SimS3ObjectVersion({
+            versionId: simS3NullVersionId,
+            key: object.key,
+            createdAt: object.lastModified,
+            object,
+        });
+    }
+    /**
+     * Whether this version records a deletion instead of holding bytes.
+     */
+    get isDeleteMarker() {
+        return this.stored === undefined;
+    }
+    /**
+     * The Object this version holds.
+     *
+     * A delete marker has none, and asking for one is a caller that skipped
+     * `isDeleteMarker`. Reporting that as an error beats handing back nothing,
+     * which reads as an empty Object further down.
+     */
+    get object() {
+        assertDefined(this.stored, `The Object of S3 version ${this.versionId} of ${this.key}, which is a delete marker`);
+        return this.stored;
+    }
+    /**
+     * When this version came into being, in simulated time.
+     *
+     * A copy, because a Date is mutable and every read of a version hands this
+     * one out.
+     */
+    get lastModified() {
+        return new Date(this.createdAt);
+    }
+    /**
+     * When this version stopped being the current one, if it has.
+     *
+     * A `NoncurrentVersionExpiration` counts from here rather than from the
+     * write, because a version written a year ago and displaced yesterday has
+     * been noncurrent for a day. Real S3 measures it the same way.
+     */
+    get noncurrentSince() {
+        const displaced = this.displaced;
+        return displaced === undefined ? undefined : new Date(displaced);
+    }
+    /**
+     * Record that a newer version has taken this one's place.
+     *
+     * Only the first displacement counts. Removing the version that displaced
+     * this one makes it current again, and a later write displaces it a second
+     * time, which real S3 measures from the later of the two.
+     */
+    displacedAt(instant) {
+        this.displaced = new Date(instant);
+    }
+    /**
+     * Record that this version is current again, which is what removing the
+     * version above it does.
+     */
+    restored() {
+        this.displaced = undefined;
+    }
+}

package/dist/service/s3/bucket/versioning/sim-s3-object-versions.d.ts

@@ -0,0 +1,52 @@
+import type { SimS3ObjectVersion } from "./sim-s3-object-version.js";
+/**
+ * The versions one simulated S3 Bucket holds, by key.
+ *
+ * Each key's versions are kept newest first, which makes the current version
+ * the head of the list and keeps a listing in the order real S3 answers in.
+ * ListObjectVersions runs through the keys in ascending order and gives each
+ * key's versions newest first, so the two orderings together are the whole
+ * response shape.
+ */
+export declare class SimS3ObjectVersions {
+    private readonly byKey;
+    /**
+     * Put a version at the head of its key, making it the current one.
+     *
+     * Whatever was at the head stops being current at that instant, and is told
+     * so, because a `NoncurrentVersionExpiration` counts from there.
+     */
+    add(version: SimS3ObjectVersion): void;
+    /**
+     * Put a version at the head of its key, dropping any other version sharing
+     * its id first.
+     *
+     * This is what a write to a suspended Bucket does. Every such write takes
+     * the null version id, and real S3 holds one version under that id rather
+     * than a run of them, so the new write replaces the old one in place.
+     */
+    replace(version: SimS3ObjectVersion): void;
+    /**
+     * The version a read of this key without a version id answers with.
+     */
+    current(key: string): SimS3ObjectVersion | undefined;
+    /**
+     * Every version of one key, newest first.
+     */
+    forKey(key: string): readonly SimS3ObjectVersion[];
+    /**
+     * One version of one key, by the id it was given.
+     */
+    find(key: string, versionId: string): SimS3ObjectVersion | undefined;
+    /**
+     * Remove one version of one key, answering the version that went.
+     *
+     * A key left with no versions is dropped rather than kept as an empty list,
+     * which is what stops a listing reporting keys nothing is stored under.
+     */
+    remove(key: string, versionId: string): SimS3ObjectVersion | undefined;
+    /**
+     * Every version this Bucket holds, in the order a listing reports them.
+     */
+    list(prefix?: string): readonly SimS3ObjectVersion[];
+}

package/dist/service/s3/bucket/versioning/sim-s3-object-versions.js

@@ -0,0 +1,91 @@
+import { compareSimS3Keys } from "./sim-s3-compare-keys.js";
+/**
+ * The versions one simulated S3 Bucket holds, by key.
+ *
+ * Each key's versions are kept newest first, which makes the current version
+ * the head of the list and keeps a listing in the order real S3 answers in.
+ * ListObjectVersions runs through the keys in ascending order and gives each
+ * key's versions newest first, so the two orderings together are the whole
+ * response shape.
+ */
+export class SimS3ObjectVersions {
+    byKey = new Map();
+    /**
+     * Put a version at the head of its key, making it the current one.
+     *
+     * Whatever was at the head stops being current at that instant, and is told
+     * so, because a `NoncurrentVersionExpiration` counts from there.
+     */
+    add(version) {
+        const versions = this.byKey.get(version.key) ?? [];
+        versions[0]?.displacedAt(version.lastModified);
+        this.byKey.set(version.key, [version, ...versions]);
+    }
+    /**
+     * Put a version at the head of its key, dropping any other version sharing
+     * its id first.
+     *
+     * This is what a write to a suspended Bucket does. Every such write takes
+     * the null version id, and real S3 holds one version under that id rather
+     * than a run of them, so the new write replaces the old one in place.
+     */
+    replace(version) {
+        this.remove(version.key, version.versionId);
+        this.add(version);
+    }
+    /**
+     * The version a read of this key without a version id answers with.
+     */
+    current(key) {
+        return this.byKey.get(key)?.[0];
+    }
+    /**
+     * Every version of one key, newest first.
+     */
+    forKey(key) {
+        return this.byKey.get(key) ?? [];
+    }
+    /**
+     * One version of one key, by the id it was given.
+     */
+    find(key, versionId) {
+        return this.forKey(key).find((version) => version.versionId === versionId);
+    }
+    /**
+     * Remove one version of one key, answering the version that went.
+     *
+     * A key left with no versions is dropped rather than kept as an empty list,
+     * which is what stops a listing reporting keys nothing is stored under.
+     */
+    remove(key, versionId) {
+        const versions = this.byKey.get(key);
+        if (versions === undefined) {
+            return undefined;
+        }
+        const removed = versions.find((version) => version.versionId === versionId);
+        const kept = versions.filter((version) => version.versionId !== versionId);
+        if (kept.length === 0) {
+            this.byKey.delete(key);
+        }
+        else {
+            // Whatever the removal left at the head is current again, and stops
+            // counting towards a noncurrent expiry.
+            if (removed === versions[0]) {
+                kept[0]?.restored();
+            }
+            this.byKey.set(key, kept);
+        }
+        return removed;
+    }
+    /**
+     * Every version this Bucket holds, in the order a listing reports them.
+     */
+    list(prefix) {
+        return this.byKey
+            .keys()
+            .filter((key) => prefix === undefined || key.startsWith(prefix))
+            .toArray()
+            .toSorted(compareSimS3Keys)
+            .flatMap((key) => this.forKey(key));
+    }
+}

package/dist/service/s3/bucket/versioning/sim-s3-version-page.d.ts

@@ -0,0 +1,32 @@
+import type { SimS3ObjectVersion } from "./sim-s3-object-version.js";
+interface SimS3VersionPageRequest {
+    readonly versions: readonly SimS3ObjectVersion[];
+    readonly maxKeys: number;
+    /** The key the previous page ended on, resumed after rather than at. */
+    readonly keyMarker?: string | undefined;
+    /**
+     * The version the previous page ended on, within `keyMarker`. Without one
+     * the whole of that key is behind the marker.
+     */
+    readonly versionIdMarker?: string | undefined;
+}
+/**
+ * One page of a version listing, and whether the Bucket holds more.
+ */
+export interface SimS3VersionPage {
+    readonly versions: readonly SimS3ObjectVersion[];
+    readonly isTruncated: boolean;
+    /** Where the next page resumes, present exactly when the listing is truncated. */
+    readonly nextKeyMarker: string | undefined;
+    readonly nextVersionIdMarker: string | undefined;
+}
+/**
+ * Take the page of a version listing that a request asked for.
+ *
+ * The markers are a pair rather than one value, because a key can hold more
+ * versions than a page has room for and resuming after the key would skip the
+ * rest of them. A `VersionIdMarker` resumes inside its key, and a `KeyMarker`
+ * on its own resumes at the key after it.
+ */
+export declare function simS3VersionPage(request: SimS3VersionPageRequest): SimS3VersionPage;
+export {};