@devultur/self-host 1.1.0 → 1.2.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as hono_types from 'hono/types';
 import { Context, MiddlewareHandler, Hono } from 'hono';
-import { Visibility, ObjectLock, SecurityPolicy, CacheRule, TranscodeSettings, TranscodeOutputKeys, TranscodeOutputUrls } from '@devultur/core';
+import { Visibility, ObjectLock, SecurityPolicy, CacheRule, TranscodeSettings, RetentionMode, TranscodeOutputKeys, TranscodeOutputUrls } from '@devultur/core';
 import { T as TranscodeContainerNamespace } from './cloudflare-kZ7J3LQ2.js';
 
 /** What an upload token allows (claims `res`, `visibility`, `max_bytes`, `max_files`, `file_ttl`, `lock`). */
@@ -444,6 +444,9 @@ declare const LOCK_UNTIL_HEADER = "x-devultur-lock-until";
 /** `true` while a hold is set. */
 declare const LOCK_HOLD_HEADER = "x-devultur-lock-hold";
 
+/** `customMetadata` key holding the lock set at upload (JSON `{ retention?, hold }`). Owned by the Worker. */
+declare const LOCK_METADATA_KEY = "lock";
+
 /** Prefixes the Worker keeps for lock sidecars and audit records: no route reads or writes a key under them. */
 declare const RESERVED_LOCK_PREFIXES: readonly ["__lock/", "__lock-audit/"];
 
@@ -458,8 +461,113 @@ interface HoldSkip {
     reason: "not_found" | "unchanged" | "lock_conflict" | "lock_record_unreadable";
 }
 
-/** `customMetadata` key holding the lock set at upload (JSON `{ retention?, hold }`). Owned by the Worker. */
-declare const LOCK_METADATA_KEY = "lock";
+/** The lock in force on one stored object. */
+interface StoredObjectLock {
+    /** True while the object can't be deleted or overwritten. */
+    locked: boolean;
+    /** A hold is set (an unreadable lock record reads as one). */
+    hold: boolean;
+    /** ISO time the retention ends; left out with no retention, or while a hold keeps a `period` from starting. */
+    until?: string;
+    mode?: RetentionMode;
+    /** The lock record can't be read, so it's held until an operator repairs it. */
+    unreadable?: true;
+    /**
+     * The key isn't laid out like the Worker's (`{storage prefix}{public|private}/…`), so its lock record can't be
+     * found: it's kept, never deleted.
+     */
+    unrecognized?: true;
+    /** Storage key of the original the lock belongs to, when it isn't the object itself (a video's raw, say). */
+    lockedBy?: string;
+}
+interface LockLookupOptions {
+    mediaBucket: R2Bucket;
+    /**
+     * The storage prefix the keys live under (the Worker's `storagePrefix`, `""` for the bucket root). Omitted: read
+     * from each key, as everything before its first `public` or `private` segment. Pass it when a prefix of yours
+     * has a segment named `public` or `private`.
+     */
+    root?: string;
+    /** Default: now. */
+    now?: Date;
+}
+/**
+ * The lock in force on the object at `storageKey` (the full R2 key), or `null` when there's no such object (or it's
+ * a lock record). A file under a video's folder (an HLS segment, a caption) is locked by the video's raws unless
+ * they're `original-only`; an image variant by its original, likewise.
+ */
+declare function readObjectLock(options: LockLookupOptions, storageKey: string): Promise<StoredObjectLock | null>;
+
+interface PrefixWalkOptions extends LockLookupOptions {
+    /** Storage prefix to walk (full R2 keys, the storage prefix of the keys included). */
+    prefix: string;
+    /** From a previous call's result, to go on where it stopped. */
+    cursor?: string;
+    /** Objects listed per page. Default 100, at most 1000. */
+    batchSize?: number;
+    /**
+     * Bucket calls this call may make. Default 40: under the free plan's 50 subrequests per request, with room for the
+     * caller's own. Raise it on a paid plan.
+     */
+    maxSubrequests?: number;
+}
+
+/**
+ * No `now`: locks are judged by the real clock, so no caller can make a retention read as expired. (The read-only
+ * `readObjectLock` and `retainedSummary` take one, to ask "what about then?".)
+ */
+interface PrefixDeleteOptions extends Omit<PrefixWalkOptions, "now"> {
+    /** The Worker's `KEYS_BUCKET`, when it has one: the encryption keys of what's deleted go too. */
+    keysBucket?: R2Bucket;
+}
+/** An object kept because it's locked (or its original is, or its key isn't laid out like the Worker's). */
+interface RetainedObject extends StoredObjectLock {
+    /** Its storage key. */
+    key: string;
+    size: number;
+}
+interface PrefixDeleteResult {
+    deletedCount: number;
+    /** The sizes of the versions deleted, read right before each delete. */
+    deletedBytes: number;
+    /** Encryption keys deleted from the keys bucket. */
+    deletedKeyCount: number;
+    retainedCount: number;
+    retainedBytes: number;
+    /** What this call kept, in key order. */
+    retained: RetainedObject[];
+    /** Lock records and audit objects passed over (never deleted). */
+    skippedCount: number;
+    /** Set when the prefix isn't done: pass it back to go on. */
+    cursor?: string;
+    /** Bucket calls this call made. */
+    subrequests: number;
+}
+/**
+ * Deletes what's free under `options.prefix` (full storage keys) and keeps what's locked. Bounded: it never makes more
+ * than `maxSubrequests` bucket calls, and returns a `cursor` to call it again with. Nothing is audited: log `retained`
+ * if you need a trail. R2 deletes aren't conditional: a lock set between an object's check and its delete isn't seen
+ * (milliseconds for its own lock; for a lock it inherits, up to `LOCK_CACHE_MAX_AGE_MS`, as that lock is cached).
+ */
+declare function deletePrefixRespectingLocks(options: PrefixDeleteOptions): Promise<PrefixDeleteResult>;
+
+interface RetainedSummary {
+    /** Objects looked at (lock records and audit not included). */
+    scannedCount: number;
+    /** What a delete would keep, keys not laid out like the Worker's included. */
+    retainedCount: number;
+    retainedBytes: number;
+    /** The latest retention end among what's retained (ISO). Holds have none: see `hasHold`. */
+    latestUntil?: string;
+    /** Something retained is held (or has an unreadable lock record): it stays until released, not until a date. */
+    hasHold: boolean;
+    /** Set when the prefix isn't done: pass it back to go on. Combine the counts of every call. */
+    cursor?: string;
+    /** Bucket calls this call made. */
+    subrequests: number;
+}
+/** What's retained under `options.prefix` (full storage keys). Bounded and resumable like the delete. */
+declare function retainedSummary(options: PrefixWalkOptions): Promise<RetainedSummary>;
 
 declare const LOCK_SIDECAR_PREFIX = "__lock/";
 interface LockSidecar {
@@ -644,4 +752,4 @@ interface CreateWorkerOptions {
 }
 declare function createWorker(options?: CreateWorkerOptions): Hono<WorkerApp, hono_types.BlankSchema, "/">;
 
-export { type AllowedCredential, type AssetListEntry, type AuthorizeLockChangeHook, type BeforeLinkRedeemHook, type ComposedPlugins, type CreateWorkerOptions, type CredentialDecision, type CredentialKind, type CredentialPolicyOptions, type CredentialRequest, DownloadLink, type DownloadLinkInfo, type DownloadLinkRecord, type DownloadLinkStorage, ENCRYPTION_KEY_MISSING_CODE, type EncodeMetrics, HOLD_PAGE_SIZE, type HoldSkip, type ImageTransformParams, type IssueCredentialHook, type Json, KEYS_BUCKET_MISSING_CODE, LOCK_AUDIT_PREFIX, LOCK_HOLD_HEADER, LOCK_METADATA_KEY, LOCK_SIDECAR_PREFIX, LOCK_UNTIL_HEADER, type LockAuditAction, type LockAuditRecord, type LockChangeAction, type LockChangeDecision, type LockChangeRequest, type LockSidecar, type LockSource, MAX_ASSET_LIST_LIMIT, MAX_EXPIRED_LOOKUPS, MAX_UPLOAD_TOKEN_TTL_SECONDS, MaxResolution, ObjectMeta, type OnLockAuditHook, type PendingUploadInfo, type PluginContext, type PluginMiddleware, type PluginRoute, RESERVED_LOCK_PREFIXES, type RawStorageClass, type RequestAccess, type RequestState, type RequestStatePatch, type RouteResult, TOKEN_REJECTED_CODE, type TranscodeConfig, type TranscodeJob, UPLOAD_TOKEN_TYPE, type UploadGrant, type UploadRules, type UploadTypeRule, type WorkerApp, WorkerAuthErrorCode, type WorkerConfig, type WorkerEnv, type WorkerPlugin, type WorkerVariables, cancelPendingUpload, createWorker, credentialPolicy, defaultPlugins, deletePrefix, downloadLinks, edgeCacheTag, getPendingUpload, getRequestState, getRouteResult, hashKey, imageOriginAuthorization, isAuthenticated, isImageOriginRequest, isObjectExpired, isOpenRoute, isServiceToken, isUploadUrl, isVariantKey, logEncodeMetrics, parseEncodeMetrics, parseTransformParams, readImageOriginScope, readStoryboardKey, readTokenScopes, readTranscodeOutputKeys, readTranscodeOutputs, servedCacheControl, staticConfig, storageKey, updateRequestState, uploadGrantFromClaims, variantPrefix, vcpuSecondsPerVideoMinute, verifyViewerToken, withOutputUrls, workerSecretAuth };
+export { type AllowedCredential, type AssetListEntry, type AuthorizeLockChangeHook, type BeforeLinkRedeemHook, type ComposedPlugins, type CreateWorkerOptions, type CredentialDecision, type CredentialKind, type CredentialPolicyOptions, type CredentialRequest, DownloadLink, type DownloadLinkInfo, type DownloadLinkRecord, type DownloadLinkStorage, ENCRYPTION_KEY_MISSING_CODE, type EncodeMetrics, HOLD_PAGE_SIZE, type HoldSkip, type ImageTransformParams, type IssueCredentialHook, type Json, KEYS_BUCKET_MISSING_CODE, LOCK_AUDIT_PREFIX, LOCK_HOLD_HEADER, LOCK_METADATA_KEY, LOCK_SIDECAR_PREFIX, LOCK_UNTIL_HEADER, type LockAuditAction, type LockAuditRecord, type LockChangeAction, type LockChangeDecision, type LockChangeRequest, type LockLookupOptions, type LockSidecar, type LockSource, MAX_ASSET_LIST_LIMIT, MAX_EXPIRED_LOOKUPS, MAX_UPLOAD_TOKEN_TTL_SECONDS, MaxResolution, ObjectMeta, type OnLockAuditHook, type PendingUploadInfo, type PluginContext, type PluginMiddleware, type PluginRoute, type PrefixDeleteOptions, type PrefixDeleteResult, type PrefixWalkOptions, RESERVED_LOCK_PREFIXES, type RawStorageClass, type RequestAccess, type RequestState, type RequestStatePatch, type RetainedObject, type RetainedSummary, type RouteResult, type StoredObjectLock, TOKEN_REJECTED_CODE, type TranscodeConfig, type TranscodeJob, UPLOAD_TOKEN_TYPE, type UploadGrant, type UploadRules, type UploadTypeRule, type WorkerApp, WorkerAuthErrorCode, type WorkerConfig, type WorkerEnv, type WorkerPlugin, type WorkerVariables, cancelPendingUpload, createWorker, credentialPolicy, defaultPlugins, deletePrefix, deletePrefixRespectingLocks, downloadLinks, edgeCacheTag, getPendingUpload, getRequestState, getRouteResult, hashKey, imageOriginAuthorization, isAuthenticated, isImageOriginRequest, isObjectExpired, isOpenRoute, isServiceToken, isUploadUrl, isVariantKey, logEncodeMetrics, parseEncodeMetrics, parseTransformParams, readImageOriginScope, readObjectLock, readStoryboardKey, readTokenScopes, readTranscodeOutputKeys, readTranscodeOutputs, retainedSummary, servedCacheControl, staticConfig, storageKey, updateRequestState, uploadGrantFromClaims, variantPrefix, vcpuSecondsPerVideoMinute, verifyViewerToken, withOutputUrls, workerSecretAuth };

package/dist/index.js

@@ -73,7 +73,7 @@ import { cors } from "hono/cors";
 import { logger } from "hono/logger";
 
 // src/object-lock/guard.ts
-import { decodeEncryptionMeta, effectiveUntil, isVideoRawKey } from "@devultur/core";
+import { isVideoRawKey } from "@devultur/core";
 
 // src/plugin-hooks.ts
 var PLUGIN_HOOKS_VARIABLE = "pluginHooks";
@@ -152,11 +152,47 @@ async function recordLockAudit(context, input) {
   await inBackground(context, deliver(context, root, record));
 }
 
+// src/object-lock/object-keys.ts
+import { decodeEncryptionMeta } from "@devultur/core";
+var DELETE_BATCH_SIZE = 1e3;
+async function listAll(bucket, options) {
+  const objects = [];
+  let cursor;
+  do {
+    const listing = await bucket.list({ ...options, ...cursor ? { cursor } : {} });
+    objects.push(...listing.objects);
+    cursor = listing.truncated ? listing.cursor : void 0;
+  } while (cursor);
+  return objects;
+}
+var isWrittenBy = (key, writtenBy) => key.uploaded.getTime() <= writtenBy.getTime();
+async function keysWrittenBy(keysBucket, prefix, writtenBy) {
+  return (await listAll(keysBucket, { prefix })).filter((key) => isWrittenBy(key, writtenBy)).map((key) => key.key);
+}
+async function objectKeysToDelete(keysBucket, fullKey, deleted) {
+  const own = await listAll(keysBucket, { prefix: `${fullKey}/`, delimiter: "/" });
+  const keys = new Set(own.filter((key) => isWrittenBy(key, deleted.uploaded)).map((key) => key.key));
+  const meta = decodeEncryptionMeta(deleted.customMetadata?.enc);
+  if (meta) keys.add(`${fullKey}/${meta.keyId}`);
+  for (const variantKey of await listAll(keysBucket, { prefix: variantPrefix(fullKey) })) keys.add(variantKey.key);
+  return [...keys];
+}
+var deleteCallsFor = (keys) => Math.ceil(keys.length / DELETE_BATCH_SIZE);
+async function deleteKeys(keysBucket, keys) {
+  for (let start = 0; start < keys.length; start += DELETE_BATCH_SIZE) {
+    await keysBucket.delete(keys.slice(start, start + DELETE_BATCH_SIZE));
+  }
+  return keys.length;
+}
+async function sweepObjectKeys(keysBucket, fullKey, deleted) {
+  return deleteKeys(keysBucket, await objectKeysToDelete(keysBucket, fullKey, deleted));
+}
+
 // src/object-lock/sidecar.ts
 import { isIsoInstant, validateLock as validateLock2 } from "@devultur/core";
 
 // src/object-lock/state.ts
-import { isLocked, validateLock } from "@devultur/core";
+import { effectiveUntil, isLocked, validateLock } from "@devultur/core";
 var LOCK_METADATA_KEY = "lock";
 function encodeLockMetadata(lock) {
   if (!lock || !lock.retention && !lock.hold) return void 0;
@@ -187,6 +223,13 @@ function isStateLocked(state, now) {
     return true;
   }
 }
+function untilOf(state) {
+  try {
+    return effectiveUntil(state.lock, { uploadedAt: state.uploadedAt, holdReleasedAt: state.holdReleasedAt });
+  } catch {
+    return void 0;
+  }
+}
 
 // src/object-lock/sidecar.ts
 var LOCK_SIDECAR_PREFIX = "__lock/";
@@ -289,32 +332,34 @@ function protectsDerived(state) {
   const derivatives = state.lock.retention?.derivatives ?? "inherit";
   return derivatives === "inherit";
 }
-async function lockedOriginal(context, root, key, now) {
-  const object = await context.env.MEDIA_BUCKET.head(`${root}${key}`);
-  const state = object ? (await effectiveLock(context.env.MEDIA_BUCKET, root, key, object)).state : null;
+async function lockedObject(bucket, root, key, object, now) {
+  const { state } = await effectiveLock(bucket, root, key, object);
   return state && isStateLocked(state, now) ? { key, state } : null;
 }
-async function lockedRaw(context, root, rawPrefix, now) {
+async function lockedOriginal(bucket, root, key, now) {
+  const object = await bucket.head(`${root}${key}`);
+  return object ? lockedObject(bucket, root, key, object, now) : null;
+}
+async function lockedRaw(bucket, root, rawPrefix, now) {
   let cursor;
   do {
-    const listing = await context.env.MEDIA_BUCKET.list({ prefix: `${root}${rawPrefix}`, cursor });
+    const listing = await bucket.list({ prefix: `${root}${rawPrefix}`, cursor });
     for (const listed of listing.objects) {
       const key = listed.key.slice(root.length);
-      const object = await context.env.MEDIA_BUCKET.head(listed.key);
-      const state = object ? (await effectiveLock(context.env.MEDIA_BUCKET, root, key, object)).state : null;
+      const object = await bucket.head(listed.key);
+      const state = object ? (await effectiveLock(bucket, root, key, object)).state : null;
       if (state && protectsDerived(state) && isStateLocked(state, now)) return { key, state };
     }
     cursor = listing.truncated ? listing.cursor : void 0;
   } while (cursor);
   return null;
 }
+function findLockedOriginal(bucket, root, subject, now) {
+  return subject.kind === "original" ? lockedOriginal(bucket, root, subject.key, now) : lockedRaw(bucket, root, subject.rawPrefix, now);
+}
 function retentionActive(context, locked, op) {
-  const { lock, uploadedAt, holdReleasedAt } = locked.state;
-  let until;
-  try {
-    until = effectiveUntil(lock, { uploadedAt, holdReleasedAt });
-  } catch {
-  }
+  const { lock } = locked.state;
+  const until = untilOf(locked.state);
   const verb = op === "delete" ? "deleted" : "overwritten";
   return context.json(
     {
@@ -339,7 +384,7 @@ async function assertWritable(context, keys, op, root = getRequestState(context)
     const subjectId = subject.kind === "original" ? subject.key : subject.rawPrefix;
     if (checked.has(subjectId)) continue;
     checked.add(subjectId);
-    const locked = subject.kind === "original" ? await lockedOriginal(context, root, subject.key, now) : await lockedRaw(context, root, subject.rawPrefix, now);
+    const locked = await findLockedOriginal(context.env.MEDIA_BUCKET, root, subject, now);
     if (!locked) continue;
     const requested = key === locked.key ? [key] : [key, locked.key];
     await recordLockAudit(context, {
@@ -355,7 +400,7 @@ async function assertWritable(context, keys, op, root = getRequestState(context)
   }
   return null;
 }
-var DELETE_BATCH_SIZE = 1e3;
+var DELETE_BATCH_SIZE2 = 1e3;
 async function guardedDeletePrefix(context, prefix) {
   const root = getRequestState(context).storagePrefix;
   const storageKeys = [];
@@ -368,38 +413,17 @@ async function guardedDeletePrefix(context, prefix) {
   const keys = storageKeys.map((key) => key.slice(root.length));
   const blocked = await assertWritable(context, keys, "delete");
   if (blocked) return { blocked };
-  for (let start = 0; start < storageKeys.length; start += DELETE_BATCH_SIZE) {
-    await context.env.MEDIA_BUCKET.delete(storageKeys.slice(start, start + DELETE_BATCH_SIZE));
+  for (let start = 0; start < storageKeys.length; start += DELETE_BATCH_SIZE2) {
+    await context.env.MEDIA_BUCKET.delete(storageKeys.slice(start, start + DELETE_BATCH_SIZE2));
   }
   return { deletedCount: storageKeys.length };
 }
-async function ownKeysOf(keysBucket, fullKey) {
-  const keys = [];
-  let cursor;
-  do {
-    const listing = await keysBucket.list({ prefix: `${fullKey}/`, delimiter: "/", cursor });
-    keys.push(...listing.objects);
-    cursor = listing.truncated ? listing.cursor : void 0;
-  } while (cursor);
-  return keys;
-}
-function isKeyOfDeletedVersion(key, deleted) {
-  return key.uploaded.getTime() <= deleted.uploaded.getTime();
-}
 async function deleteKeysFor(context, objectKey, deleted) {
   const blocked = await assertWritable(context, [objectKey], "delete");
   if (blocked) return { blocked };
   const keysBucket = context.env.KEYS_BUCKET;
   if (!keysBucket) return { deletedCount: 0 };
-  const fullKey = storageKey(context, objectKey);
-  const ownKeys = new Set(
-    (await ownKeysOf(keysBucket, fullKey)).filter((key) => isKeyOfDeletedVersion(key, deleted)).map((key) => key.key)
-  );
-  const meta = decodeEncryptionMeta(deleted.customMetadata?.enc);
-  if (meta) ownKeys.add(`${fullKey}/${meta.keyId}`);
-  if (ownKeys.size > 0) await keysBucket.delete([...ownKeys]);
-  const variantKeyCount = await deletePrefix(keysBucket, variantPrefix(fullKey));
-  return { deletedCount: variantKeyCount + ownKeys.size };
+  return { deletedCount: await sweepObjectKeys(keysBucket, storageKey(context, objectKey), deleted) };
 }
 async function deleteFolderKeys(context, videoFolder) {
   const blocked = await assertWritable(context, [videoFolder], "delete");
@@ -4923,6 +4947,315 @@ upload.put("/:key{.+}", async (context) => {
   return context.json({ key, size: body.byteLength, sha256: digest.sha256, sha256Verified: true });
 });
 
+// src/object-lock/lock-status.ts
+var VISIBILITY_SEGMENTS = /* @__PURE__ */ new Set(["public", "private"]);
+var RESERVED_SEGMENT = /__lock(?:-audit)?$/;
+function placeOfStorageKey(storageKey2, root) {
+  const segments = storageKey2.split("/");
+  if (segments.some((segment) => RESERVED_SEGMENT.test(segment))) return { kind: "reserved" };
+  if (root !== void 0) {
+    const key = storageKey2.slice(root.length);
+    const isWorkerKey = storageKey2.startsWith(root) && VISIBILITY_SEGMENTS.has(key.split("/")[0] ?? "");
+    return isWorkerKey ? { kind: "object", root, key } : { kind: "unrecognized" };
+  }
+  const first = segments.findIndex((segment) => VISIBILITY_SEGMENTS.has(segment));
+  if (first < 0) return { kind: "unrecognized" };
+  const inferredRoot = first === 0 ? "" : `${segments.slice(0, first).join("/")}/`;
+  return { kind: "object", root: inferredRoot, key: storageKey2.slice(inferredRoot.length) };
+}
+var UNRECOGNIZED_LOCK = { locked: true, hold: false, unrecognized: true };
+var VARIANTS_SEGMENT = "/__variants/";
+function retentionSubjectOf(key) {
+  const isVariant = isVariantKey(key);
+  const original = isVariant ? key.slice(0, key.indexOf(VARIANTS_SEGMENT)) : key;
+  return { subject: lockSubjectOf(original) ?? { kind: "original", key: original }, isVariant };
+}
+function toStoredObjectLock(locked, place) {
+  if (!locked) return { locked: false, hold: false };
+  const { lock, isUnreadable } = locked.state;
+  const until = untilOf(locked.state);
+  return {
+    locked: true,
+    hold: lock.hold === true,
+    ...until ? { until } : {},
+    ...lock.retention ? { mode: lock.retention.mode } : {},
+    ...isUnreadable ? { unreadable: true } : {},
+    ...locked.key === place.key ? {} : { lockedBy: `${place.root}${locked.key}` }
+  };
+}
+var LOCK_CACHE_MAX_USES = 50;
+var LOCK_CACHE_MAX_AGE_MS = 5e3;
+function lockResolver(mediaBucket, now) {
+  const cache = /* @__PURE__ */ new Map();
+  const resolveSubject = (root, subject) => {
+    const id = `${root}\0${subject.kind === "original" ? subject.key : subject.rawPrefix}`;
+    const cached = cache.get(id);
+    const isFresh = cached && cached.uses < LOCK_CACHE_MAX_USES && Date.now() - cached.readAt < LOCK_CACHE_MAX_AGE_MS;
+    if (cached && isFresh) {
+      cached.uses += 1;
+      return cached.pending;
+    }
+    const pending = findLockedOriginal(mediaBucket, root, subject, now);
+    pending.catch(() => cache.delete(id));
+    cache.set(id, { pending, readAt: Date.now(), uses: 1 });
+    return pending;
+  };
+  return async (place, object) => {
+    const { subject, isVariant } = retentionSubjectOf(place.key);
+    if (subject.kind === "original" && subject.key === place.key) {
+      return lockedObject(mediaBucket, place.root, place.key, object, now);
+    }
+    const locked = await resolveSubject(place.root, subject);
+    if (isVariant && subject.kind === "original" && locked && !protectsDerived(locked.state)) return null;
+    return locked;
+  };
+}
+async function readObjectLock(options, storageKey2) {
+  const place = placeOfStorageKey(storageKey2, options.root);
+  if (place.kind === "reserved") return null;
+  const object = await options.mediaBucket.head(storageKey2);
+  if (!object) return null;
+  if (place.kind === "unrecognized") return UNRECOGNIZED_LOCK;
+  const locked = await lockResolver(options.mediaBucket, options.now ?? /* @__PURE__ */ new Date())(place, object);
+  return toStoredObjectLock(locked, place);
+}
+
+// src/object-lock/prefix-walk.ts
+var DEFAULT_MAX_SUBREQUESTS = 40;
+var DEFAULT_BATCH_SIZE = 100;
+var MAX_BATCH_SIZE = 1e3;
+var BudgetExhausted = class extends Error {
+  constructor() {
+    super("subrequest budget exhausted");
+  }
+};
+function subrequestBudget(max) {
+  if (!Number.isInteger(max) || max < 1) throw new RangeError("maxSubrequests must be a positive integer");
+  let used = 0;
+  return {
+    get used() {
+      return used;
+    },
+    canAfford: (count) => used + count <= max,
+    track: (bucket) => new Proxy(bucket, {
+      get(target, property) {
+        const value = Reflect.get(target, property);
+        if (typeof value !== "function") return value;
+        return (...args) => {
+          if (used >= max) throw new BudgetExhausted();
+          used += 1;
+          return value.apply(target, args);
+        };
+      }
+    })
+  };
+}
+function encodeCursor(prefix, cursor) {
+  return btoa(JSON.stringify({ prefix, ...cursor }));
+}
+var VIDEO_FOLDER_SHAPE = /^(?:public|private)\/video\/[^/]+$/;
+function invalidCursor(reason) {
+  throw new RangeError(`cursor isn't one this function returned for this prefix: ${reason}`);
+}
+function parseCursor(cursor) {
+  try {
+    const parsed = JSON.parse(atob(cursor));
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed))
+      return parsed;
+  } catch {
+  }
+  return invalidCursor("not a cursor");
+}
+var isOptionalString = (value) => value === void 0 || typeof value === "string";
+function validFolder(value, options) {
+  if (value === void 0) return void 0;
+  const { root, folder } = typeof value === "object" && value !== null ? value : {};
+  if (typeof root !== "string" || typeof folder !== "string" || !VIDEO_FOLDER_SHAPE.test(folder)) {
+    return invalidCursor("folder");
+  }
+  const folderPrefix = `${root}${folder}/`;
+  const place = placeOfStorageKey(`${folderPrefix}x`, options.root);
+  const isPlaced = place.kind === "object" && place.root === root;
+  if (!isPlaced || !folderPrefix.startsWith(options.prefix)) return invalidCursor("folder outside the prefix");
+  return { root, folder };
+}
+function decodeCursor(cursor, options) {
+  if (cursor === void 0) return {};
+  const { prefix, after, listCursor, folder } = parseCursor(cursor);
+  if (prefix !== options.prefix) return invalidCursor("another prefix");
+  if (!isOptionalString(after) || !isOptionalString(listCursor)) return invalidCursor("position");
+  if (typeof after === "string" && !after.startsWith(options.prefix))
+    return invalidCursor("position outside the prefix");
+  const pendingFolder = validFolder(folder, options);
+  return {
+    ...typeof after === "string" ? { after } : {},
+    ...typeof listCursor === "string" ? { listCursor } : {},
+    ...pendingFolder ? { folder: pendingFolder } : {}
+  };
+}
+async function walkPrefix(options, mediaBucket, start, visit) {
+  const limit = Math.min(Math.max(1, Math.floor(options.batchSize ?? DEFAULT_BATCH_SIZE)), MAX_BATCH_SIZE);
+  let position = { ...start };
+  let hasProgressed = false;
+  const stopped = () => ({ position, isDone: false, hasProgressed });
+  for (; ; ) {
+    let listing;
+    try {
+      listing = await mediaBucket.list({ prefix: options.prefix, limit, ...listFrom(position) });
+    } catch (error) {
+      if (error instanceof BudgetExhausted) return stopped();
+      throw error;
+    }
+    const stray = listing.objects.find((listed) => !listed.key.startsWith(options.prefix));
+    if (stray) throw new RangeError(`listing returned ${stray.key}, outside the prefix ${options.prefix}`);
+    for (const listed of listing.objects) {
+      try {
+        await visit({ listed, place: placeOfStorageKey(listed.key, options.root) });
+      } catch (error) {
+        if (error instanceof BudgetExhausted) return stopped();
+        throw error;
+      }
+      position = { after: listed.key };
+      hasProgressed = true;
+    }
+    if (!listing.truncated) return { position, isDone: true, hasProgressed };
+    if (listing.objects.length > 0) continue;
+    position = { ...position, listCursor: listing.cursor };
+    hasProgressed = true;
+  }
+}
+function listFrom(position) {
+  if (position.listCursor) return { cursor: position.listCursor };
+  return position.after ? { startAfter: position.after } : {};
+}
+function assertProgress(hasProgressed) {
+  if (hasProgressed) return;
+  throw new RangeError("maxSubrequests is too small to finish the next object: raise it");
+}
+
+// src/object-lock/prefix-delete.ts
+var VIDEO_FOLDER = /^((?:public|private)\/video\/[^/]+)\//;
+var isPending = (folder) => folder?.hasDeleted === true && !folder.hasRetained;
+async function deletePrefixRespectingLocks(options) {
+  const startedAt = /* @__PURE__ */ new Date();
+  const budget = subrequestBudget(options.maxSubrequests ?? DEFAULT_MAX_SUBREQUESTS);
+  const mediaBucket = budget.track(options.mediaBucket);
+  const keysBucket = options.keysBucket ? budget.track(options.keysBucket) : void 0;
+  const resolveLock3 = lockResolver(mediaBucket, startedAt);
+  const start = decodeCursor(options.cursor, options);
+  const result = {
+    deletedCount: 0,
+    deletedBytes: 0,
+    deletedKeyCount: 0,
+    retainedCount: 0,
+    retainedBytes: 0,
+    retained: [],
+    skippedCount: 0,
+    subrequests: 0
+  };
+  let openFolder = start.folder ? { ...start.folder, hasDeleted: true, hasRetained: false } : null;
+  let hasClosed = false;
+  const closeFolder = async () => {
+    if (isPending(openFolder)) {
+      const { root, folder } = openFolder;
+      const folderPrefix = `${root}${folder}/`;
+      const remaining = await mediaBucket.list({ prefix: folderPrefix, limit: 1 });
+      if (remaining.objects.length === 0) {
+        if (keysBucket) {
+          const keys = await keysWrittenBy(keysBucket, folderPrefix, startedAt);
+          result.deletedKeyCount += await deleteKeys(keysBucket, keys);
+        }
+        await forgetTranscodeCompleted(mediaBucket, root, folder);
+      }
+      hasClosed = true;
+    }
+    openFolder = null;
+  };
+  const enterFolder = async (place) => {
+    const videoFolder = VIDEO_FOLDER.exec(place.key)?.[1];
+    const folder = videoFolder && `${place.root}${videoFolder}/`.startsWith(options.prefix) ? videoFolder : void 0;
+    if (openFolder && openFolder.root === place.root && openFolder.folder === folder) return openFolder;
+    await closeFolder();
+    openFolder = folder ? { root: place.root, folder, hasDeleted: false, hasRetained: false } : null;
+    return openFolder;
+  };
+  const retain = (key, size, lock) => {
+    result.retained.push({ key, size, ...lock });
+    result.retainedCount += 1;
+    result.retainedBytes += size;
+  };
+  const visit = async ({ listed, place }) => {
+    if (place.kind === "reserved") {
+      result.skippedCount += 1;
+      return;
+    }
+    if (place.kind === "unrecognized") return retain(listed.key, listed.size, UNRECOGNIZED_LOCK);
+    const folder = await enterFolder(place);
+    const object = await mediaBucket.head(listed.key);
+    if (!object) return;
+    const locked = await resolveLock3(place, object);
+    if (locked) {
+      if (folder) folder.hasRetained = true;
+      return retain(listed.key, object.size, toStoredObjectLock(locked, place));
+    }
+    const keys = keysBucket ? await objectKeysToDelete(keysBucket, listed.key, object) : [];
+    if (!budget.canAfford(1 + deleteCallsFor(keys))) throw new BudgetExhausted();
+    await mediaBucket.delete(listed.key);
+    result.deletedCount += 1;
+    result.deletedBytes += object.size;
+    if (folder) folder.hasDeleted = true;
+    if (keysBucket) result.deletedKeyCount += await deleteKeys(keysBucket, keys);
+  };
+  const walk = await walkPrefix(options, mediaBucket, start, visit);
+  if (walk.isDone) {
+    try {
+      await closeFolder();
+    } catch (error) {
+      if (!(error instanceof BudgetExhausted)) throw error;
+    }
+  }
+  const pendingFolder = isPending(openFolder) ? { root: openFolder.root, folder: openFolder.folder } : void 0;
+  const isFinished = walk.isDone && !pendingFolder;
+  assertProgress(walk.hasProgressed || hasClosed || isFinished);
+  const cursor = isFinished ? void 0 : encodeCursor(options.prefix, { ...walk.position, ...pendingFolder ? { folder: pendingFolder } : {} });
+  return { ...result, ...cursor ? { cursor } : {}, subrequests: budget.used };
+}
+
+// src/object-lock/retained-summary.ts
+async function retainedSummary(options) {
+  const budget = subrequestBudget(options.maxSubrequests ?? DEFAULT_MAX_SUBREQUESTS);
+  const mediaBucket = budget.track(options.mediaBucket);
+  const resolveLock3 = lockResolver(mediaBucket, options.now ?? /* @__PURE__ */ new Date());
+  const summary = {
+    scannedCount: 0,
+    retainedCount: 0,
+    retainedBytes: 0,
+    hasHold: false,
+    subrequests: 0
+  };
+  const visit = async ({ listed, place }) => {
+    if (place.kind === "reserved") return;
+    let lock = UNRECOGNIZED_LOCK;
+    let size = listed.size;
+    if (place.kind === "object") {
+      const object = await mediaBucket.head(listed.key);
+      if (!object) return;
+      lock = toStoredObjectLock(await resolveLock3(place, object), place);
+      size = object.size;
+    }
+    summary.scannedCount += 1;
+    if (!lock.locked) return;
+    summary.retainedCount += 1;
+    summary.retainedBytes += size;
+    if (lock.hold) summary.hasHold = true;
+    if (lock.until && (!summary.latestUntil || lock.until > summary.latestUntil)) summary.latestUntil = lock.until;
+  };
+  const walk = await walkPrefix(options, mediaBucket, decodeCursor(options.cursor, options), visit);
+  assertProgress(walk.hasProgressed || walk.isDone);
+  const cursor = walk.isDone ? void 0 : encodeCursor(options.prefix, walk.position);
+  return { ...summary, ...cursor ? { cursor } : {}, subrequests: budget.used };
+}
+
 // src/index.ts
 function createWorker(options) {
   const { middleware, routes, hooks } = composePlugins(options?.plugins ?? defaultPlugins());
@@ -4985,6 +5318,7 @@ export {
   credentialPolicy,
   defaultPlugins,
   deletePrefix,
+  deletePrefixRespectingLocks,
   downloadLinks,
   edgeCacheTag,
   getPendingUpload,
@@ -5003,10 +5337,12 @@ export {
   parseEncodeMetrics,
   parseTransformParams,
   readImageOriginScope,
+  readObjectLock,
   readStoryboardKey,
   readTokenScopes,
   readTranscodeOutputKeys,
   readTranscodeOutputs,
+  retainedSummary,
   servedCacheControl,
   staticConfig,
   storageKey,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@devultur/self-host",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Self-hosted media Worker for Cloudflare: R2 uploads, edge-cached delivery, image transforms, HLS transcode and captions",
   "keywords": [
     "cloudflare-workers",
@@ -46,7 +46,7 @@
     "@jsquash/resize": "2.1.1",
     "@jsquash/webp": "1.5.0",
     "hono": "^4.7.0",
-    "@devultur/core": "1.1.0"
+    "@devultur/core": "1.2.0"
   },
   "devDependencies": {
     "@cf-wasm/photon": "0.4.0",