@occultist/occultist 0.0.4 → 0.0.6

package/dist/cache/file.d.ts

@@ -1,14 +1,46 @@
-import type { CacheDetails, CacheHitHandle, CacheMeta, CacheStorage, CacheMissHandle } from './types.js';
+import type { CacheDetails, CacheHitHandle, CacheMeta, CacheStorage, CacheMissHandle, UpstreamCache } from './types.ts';
+import { Registry } from '../registry.ts';
+import { Cache } from './cache.ts';
+/**
+ * Stores cache meta information in a file on the filesystem.
+ *
+ * This is not robust enough for multi-process use.
+ */
 export declare class FileCacheMeta implements CacheMeta {
     #private;
     constructor(filePath: string);
     get(key: string): Promise<CacheHitHandle | CacheMissHandle>;
+    /**
+     * Sets a cached value.
+     *
+     * @param key Unique key for this cached value.
+     * @param details Details of the cache to store.
+     */
     set(key: string, details: CacheDetails): Promise<void>;
+    /**
+     * Invalidates a cached value by key.
+     *
+     * @param key Unique key for this cached value.
+     */
+    invalidate(key: string): Promise<void>;
+    /**
+     * Flushes the entire cache of values.
+     *
+     * @param key Unique key for this cached value.
+     */
+    flush(): Promise<void>;
 }
 export declare class FileSystemCacheStorage implements CacheStorage {
     #private;
+    constructor(directory: string);
     hash(key: string): string;
     get(key: string): Promise<Blob>;
     set(key: string, value: Blob): Promise<void>;
     invalidate(key: string): Promise<void>;
+    flush(): Promise<void>;
+}
+export declare class FileSystemCache extends Cache {
+    #private;
+    constructor(registry: Registry, filePath: string, directory: string, upstream?: UpstreamCache);
+    flush(): Promise<[void, void]>;
 }

package/dist/cache/file.js

@@ -1,22 +1,40 @@
 import { createHash } from 'node:crypto';
-import { open, readFile, writeFile, rm } from 'node:fs/promises';
+import { readFile, writeFile, rm } from 'node:fs/promises';
 import { join } from 'node:path';
+import { watchFile } from 'node:fs';
+import { Cache } from "./cache.js";
+/**
+ * Stores cache meta information in a file on the filesystem.
+ *
+ * This is not robust enough for multi-process use.
+ */
 export class FileCacheMeta {
     #filePath;
-    #handle;
     #details = {};
+    #watcher;
+    #writing = false;
     constructor(filePath) {
         this.#filePath = filePath;
     }
     async #init() {
-        this.#handle = await open(this.#filePath, 'w+');
-        const content = await this.#handle.readFile({ encoding: 'utf-8' });
-        this.#details = JSON.parse(content);
+        try {
+            const content = await readFile(this.#filePath, 'utf-8');
+            this.#details = JSON.parse(content);
+        }
+        catch (err) {
+            await writeFile(this.#filePath, JSON.stringify(this.#details));
+        }
+        this.#watcher = watchFile(this.#filePath, async () => {
+            if (this.#writing)
+                return;
+            const content = await readFile(this.#filePath, 'utf-8');
+            this.#details = JSON.parse(content);
+        });
+        this.#watcher.unref();
     }
     async get(key) {
-        if (this.#handle == null) {
-            this.#init();
-        }
+        if (this.#watcher == null)
+            await this.#init();
         const details = this.#details[key];
         async function set(details) {
             this.#details.set(key, details);
@@ -33,19 +51,58 @@ export class FileCacheMeta {
             set,
         };
     }
+    /**
+     * Sets a cached value.
+     *
+     * @param key Unique key for this cached value.
+     * @param details Details of the cache to store.
+     */
     async set(key, details) {
+        if (this.#watcher == null)
+            await this.#init();
         this.#details[key] = details;
-        this.#handle.writeFile(JSON.stringify(details));
+        await this.#write();
+    }
+    /**
+     * Invalidates a cached value by key.
+     *
+     * @param key Unique key for this cached value.
+     */
+    async invalidate(key) {
+        if (this.#watcher == null)
+            await this.#init();
+        delete this.#details[key];
+        await this.#write();
+    }
+    /**
+     * Flushes the entire cache of values.
+     *
+     * @param key Unique key for this cached value.
+     */
+    async flush() {
+        this.#details = {};
+        await this.#write();
+    }
+    async #write() {
+        this.#writing = true;
+        try {
+            await writeFile(this.#filePath, JSON.stringify(this.#details));
+        }
+        catch { }
+        this.#writing = false;
     }
 }
 export class FileSystemCacheStorage {
     #directory;
     #hashes = new Map();
+    constructor(directory) {
+        this.#directory = directory;
+    }
     hash(key) {
         let hash = this.#hashes.get(key);
         if (hash != null)
             return hash;
-        hash = createHash('md5').update(key).digest('hex');
+        hash = createHash('sha256').update(key).digest('hex');
         this.#hashes.set(key, hash);
         return hash;
     }
@@ -59,4 +116,29 @@ export class FileSystemCacheStorage {
     async invalidate(key) {
         await rm(join(this.#directory, this.hash(key)));
     }
+    async flush() {
+        const promises = [];
+        for (const hash of this.#hashes.values()) {
+            promises.push(rm(join(this.#directory, hash)));
+        }
+        this.#hashes = new Map();
+        await Promise.all(promises);
+    }
+}
+export class FileSystemCache extends Cache {
+    #fileMeta;
+    #fileSystemStorage;
+    constructor(registry, filePath, directory, upstream) {
+        const meta = new FileCacheMeta(filePath);
+        const storage = new FileSystemCacheStorage(directory);
+        super(registry, meta, storage, upstream);
+        this.#fileMeta = meta;
+        this.#fileSystemStorage = storage;
+    }
+    async flush() {
+        return Promise.all([
+            this.#fileMeta.flush(),
+            this.#fileSystemStorage.flush(),
+        ]);
+    }
 }

package/dist/cache/memory.d.ts

@@ -1,12 +1,22 @@
-import type { CacheDetails, CacheHitHandle, CacheMeta, CacheStorage, CacheMissHandle } from './types.js';
+import { Registry } from '../registry.ts';
+import type { CacheDetails, CacheHitHandle, CacheMeta, CacheStorage, CacheMissHandle, UpstreamCache, LockedCacheMissHandle } from './types.ts';
+import { Cache } from './cache.ts';
 export declare class InMemoryCacheMeta implements CacheMeta {
     #private;
     get(key: string): Promise<CacheHitHandle | CacheMissHandle>;
-    set(key: string, details: CacheDetails): Promise<void>;
+    set(key: string, details: CacheDetails): void;
+    getOrLock(key: string): Promise<CacheHitHandle | LockedCacheMissHandle>;
+    invalidate(key: string): void;
+    flush(): Promise<void>;
 }
 export declare class InMemoryCacheStorage implements CacheStorage {
     #private;
     get(key: string): Blob;
     set(key: string, value: Blob): void;
     invalidate(key: string): void;
+    flush(): void;
+}
+export declare class InMemoryCache extends Cache {
+    constructor(registry: Registry, upstream?: UpstreamCache);
+    flush(): Promise<void>;
 }

package/dist/cache/memory.js

@@ -1,6 +1,12 @@
+import { Cache } from "./cache.js";
 export class InMemoryCacheMeta {
     #details = new Map();
+    #locks = new Map();
+    #flushLock;
     async get(key) {
+        if (this.#flushLock) {
+            await this.#flushLock;
+        }
         const details = this.#details.get(key);
         async function set(details) {
             this.#details.set(key, details);
@@ -17,9 +23,53 @@ export class InMemoryCacheMeta {
             set,
         };
     }
-    async set(key, details) {
+    set(key, details) {
         this.#details.set(key, details);
     }
+    async getOrLock(key) {
+        if (this.#flushLock) {
+            await this.#flushLock;
+        }
+        const lock = this.#locks.get(key);
+        if (lock != null) {
+            await lock;
+        }
+        const details = this.#details.get(key);
+        const { resolve, promise } = Promise.withResolvers();
+        this.#locks.set(key, promise);
+        function set(details) {
+            this.#details.set(key, details);
+        }
+        const release = () => {
+            resolve();
+            this.#locks.delete(key);
+        };
+        if (details == null) {
+            return {
+                type: 'locked-cache-miss',
+                set,
+                release,
+            };
+        }
+        return {
+            ...details,
+            type: 'cache-hit',
+            set,
+        };
+    }
+    invalidate(key) {
+        this.#details.delete(key);
+    }
+    async flush() {
+        const { resolve, promise } = Promise.withResolvers();
+        this.#flushLock = promise;
+        // there could be a race condition here where the values are
+        // flused before queued requests can get them.
+        await Promise.all(this.#locks.values());
+        this.#details = new Map();
+        this.#locks = new Map();
+        resolve();
+    }
 }
 export class InMemoryCacheStorage {
     #cache = new Map();
@@ -33,4 +83,16 @@ export class InMemoryCacheStorage {
     invalidate(key) {
         this.#cache.delete(key);
     }
+    flush() {
+        this.#cache = new Map();
+    }
+}
+export class InMemoryCache extends Cache {
+    constructor(registry, upstream) {
+        super(registry, new InMemoryCacheMeta(), new InMemoryCacheStorage(), upstream);
+    }
+    async flush() {
+        await this.meta.flush();
+        this.storage.flush();
+    }
 }

package/dist/cache/types.d.ts

@@ -1,13 +1,15 @@
-import { ImplementedAction } from "../actions/types.js";
-import { CacheContext } from "../mod.js";
+import type { AuthState, ImplementedAction } from "../actions/types.ts";
+import type { CacheContext } from "../mod.ts";
 export type CacheStrategyType = 'http' | 'etag' | 'store';
+export type CacheSemantics = 'options' | 'head' | 'get' | 'post' | 'put' | 'delete' | 'query';
 export interface CacheEntryDescriptor {
     contentType: string;
+    semantics: CacheSemantics;
     action: ImplementedAction;
     request: Request;
     args: CacheInstanceArgs;
 }
-export type CacheWhenFn = (ctx: CacheContext) => boolean;
+export type CacheWhenFn<Auth extends AuthState = AuthState> = (ctx: CacheContext<Auth>) => boolean;
 export type CacheRuleArgs = {
     /**
      * A version which should increment every when a new release
@@ -22,6 +24,10 @@ export type CacheRuleArgs = {
     vary?: string;
     varyOnAuth?: boolean;
     varyOnCapabilities?: string | string[];
+    /**
+     * Overrides the semantics of the cache.
+     */
+    semantics?: CacheSemantics;
     /**
      * Defaults to false when a querystring is present
      * or the request is authenticated.
@@ -32,7 +38,7 @@ export type CacheRuleArgs = {
 };
 export type CacheControlArgs = {
     private?: boolean;
-    public?: true;
+    publicWhenAuthenticated?: true;
     noCache?: true;
     noStore?: true;
     mustRevalidate?: true;
@@ -45,7 +51,6 @@ export type CacheControlArgs = {
     etag?: string;
 };
 export type CacheHTTPArgs = {
-    strategy: 'http';
     strong?: undefined;
     fromRequest?: undefined;
 } & CacheRuleArgs & CacheControlArgs;
@@ -54,17 +59,15 @@ export type CacheHTTPInstanceArgs = CacheHTTPArgs & {
     cache: CacheBuilder;
 };
 export type CacheETagArgs = {
-    strategy: 'etag';
     strong?: boolean;
     fromRequest?: boolean;
     etag?: undefined;
 } & CacheRuleArgs & Omit<CacheControlArgs, 'etag'>;
 export type CacheETagInstanceArgs = CacheETagArgs & {
-    stratey: 'etag';
+    strategy: 'etag';
     cache: CacheBuilder;
 };
 export type CacheStoreArgs = {
-    strategy: 'store';
     strong?: boolean;
     fromRequest?: boolean;
     etag?: undefined;
@@ -81,7 +84,7 @@ export type CacheDetails = {
     hasContent: boolean;
     authKey: string;
     etag: string;
-    headers: Headers;
+    headers: Record<string, string | string[]>;
     contentType: string;
     contentLength?: number;
     contentEncoding?: string;
@@ -90,16 +93,16 @@ export type CacheDetails = {
 };
 export type CacheHitHandle = CacheDetails & {
     type: 'cache-hit';
-    set(details: CacheDetails): Promise<void>;
+    set(details: CacheDetails): void | Promise<void>;
 };
 export type CacheMissHandle = {
     type: 'cache-miss';
-    set(details: CacheDetails): Promise<void>;
+    set(details: CacheDetails): void | Promise<void>;
 };
 export type LockedCacheMissHandle = {
     type: 'locked-cache-miss';
-    set(details: CacheDetails): Promise<void>;
-    release(): Promise<void>;
+    set(details: CacheDetails): void | Promise<void>;
+    release(): void | Promise<void>;
 };
 /**
  * The cache meta knows how to query a storage for current freshness
@@ -114,26 +117,45 @@ export interface CacheMeta {
     /**
      * Sets the cache details for a representation.
      *
-     * @param key       A unique key for this representation.
-     * @param details   The cache details.
+     * @param key Unique key for this cached value.
+     * @param details Details of the cache to store.
      */
     set(key: string, details: CacheDetails): void | Promise<void>;
     /**
      * Retrieves the cache details of a representation.
      *
-     * @param key       A unique key for this representation.
+     * @param key Unique key for this cached value.
      */
     get(key: string): CacheHitHandle | CacheMissHandle | Promise<CacheHitHandle | CacheMissHandle>;
     /**
      * Retrieves the cache details of a representation and takes a lock
-     * for update if the representation is not current.
+     * for update if the representation is not current. All concurrent requests
+     * targeting the same cached value will wait for the cache to be populated
+     * and respond from cache. This can occur across processes if the locking
+     * mechanism allows for it.
+     *
+     * This is an experimental API and its benifits are untested. APIs that
+     * have a high failure rate could see degredation in services as requests
+     * will queue to take the lock, but fail to set a new cache value causing
+     * the queued requests to continue locking.
      *
-     * Any other requests for this representation will wait for the request
-     * holding the lock to populate the cache before proceeding.
+     * However, this could help protect downstream services from thundering herd
+     * like scenarios as only one requester will build the representation that all
+     * requesters use.
      *
-     * @param key   A unique key for this representation.
+     * @param key Unique key for this cached value.
      */
     getOrLock?(key: string): Promise<CacheHitHandle | LockedCacheMissHandle>;
+    /**
+     * Invalidates a cached value by key.
+     *
+     * @param key Unique key for this cached value.
+     */
+    invalidate(key: string): void | Promise<void>;
+    /**
+     * Flushes the entire cache of values.
+     */
+    flush(): void | Promise<void>;
 }
 export interface UpstreamCache {
     /**
@@ -159,9 +181,13 @@ export interface CacheStorage {
      */
     set(key: string, data: Blob): void | Promise<void>;
     /**
-     * Invalidates a cache entry.
+     * Deletes a cache entry.
      */
     invalidate(key: string): void | Promise<void>;
+    /**
+     * Flushes the entire cache of values.
+     */
+    flush(): void | Promise<void>;
 }
 export interface CacheBuilder {
     meta: CacheMeta;
@@ -170,6 +196,9 @@ export interface CacheBuilder {
     http(args?: CacheHTTPArgs): CacheInstanceArgs;
     etag(args?: CacheETagArgs): CacheInstanceArgs;
     store(args?: CacheStoreArgs): CacheInstanceArgs;
-    invalidate?(request: Request): Promise<void>;
+    /**
+     * Removes an item from the cache.
+     */
+    invalidate(key: string, url: string): void | Promise<void>;
     push?(request: Request): Promise<void>;
 }

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-import { ProblemDetails } from "./types.js";
+import type { ProblemDetails } from "./types.ts";
 export declare class ProblemDetailsError extends Error {
     status: number;
     problemDetails: ProblemDetails;

package/dist/jsonld.d.ts

@@ -1,4 +1,4 @@
-import type { ShallowMerge } from "./merge.js";
+import type { ShallowMerge } from "./merge.ts";
 export type RecursiveDigit = 1 | 2 | 3 | 4 | 5 | 6 | 7;
 export type RecursiveNextDigit = [1, 2, 3, 4, 5, 6, 7, 'STOP'];
 export type RecursiveIncrement<T> = T extends RecursiveDigit ? RecursiveNextDigit[T] : 'STOP';

package/dist/makeTypeDefs.d.ts

@@ -1,5 +1,5 @@
-import type { ContextDefinitionContainer, TypeDef } from "./jsonld.js";
-import type { Context } from "./actions/context.js";
+import type { ContextDefinitionContainer, TypeDef } from "./jsonld.ts";
+import type { Context } from "./actions/context.ts";
 export type MakeTypeDefArgsFromType<Term extends string, Type extends string> = {
     term: Term;
     type: Type;

package/dist/mod.d.ts

@@ -1,15 +1,17 @@
-export * from './cache/types.js';
-export * from './cache/cache.js';
-export * from './cache/memory.js';
-export * from './cache/file.js';
-export * from './actions/types.js';
-export * from './actions/meta.js';
-export * from './actions/spec.js';
-export * from './actions/context.js';
-export * from './actions/path.js';
-export * from './actions/actions.js';
-export * from './actions/actionSets.js';
-export * from './registry.js';
-export * from './makeTypeDefs.js';
-export * from './utils/joinPaths.js';
-export * from './utils/contextBuilder.js';
+export * from './cache/types.ts';
+export * from './cache/cache.ts';
+export * from './cache/memory.ts';
+export * from './cache/file.ts';
+export * from './actions/types.ts';
+export * from './actions/meta.ts';
+export * from './actions/spec.ts';
+export * from './actions/context.ts';
+export * from './actions/path.ts';
+export * from './actions/actions.ts';
+export * from './actions/actionSets.ts';
+export * from './request.ts';
+export * from './actions/writer.ts';
+export * from './registry.ts';
+export * from './makeTypeDefs.ts';
+export * from './utils/joinPaths.ts';
+export * from './utils/contextBuilder.ts';

package/dist/mod.js

@@ -1,15 +1,17 @@
-export * from './cache/types.js';
-export * from './cache/cache.js';
-export * from './cache/memory.js';
-export * from './cache/file.js';
-export * from './actions/types.js';
-export * from './actions/meta.js';
-export * from './actions/spec.js';
-export * from './actions/context.js';
-export * from './actions/path.js';
-export * from './actions/actions.js';
-export * from './actions/actionSets.js';
-export * from './registry.js';
-export * from './makeTypeDefs.js';
-export * from './utils/joinPaths.js';
-export * from './utils/contextBuilder.js';
+export * from "./cache/types.js";
+export * from "./cache/cache.js";
+export * from "./cache/memory.js";
+export * from "./cache/file.js";
+export * from "./actions/types.js";
+export * from "./actions/meta.js";
+export * from "./actions/spec.js";
+export * from "./actions/context.js";
+export * from "./actions/path.js";
+export * from "./actions/actions.js";
+export * from "./actions/actionSets.js";
+export * from "./request.js";
+export * from "./actions/writer.js";
+export * from "./registry.js";
+export * from "./makeTypeDefs.js";
+export * from "./utils/joinPaths.js";
+export * from "./utils/contextBuilder.js";

package/dist/processAction.d.ts

@@ -1,5 +1,5 @@
-import type { ImplementedAction } from "./actions/types.js";
-import type { ActionPayload, ActionSpec, ContextState, ParsedIRIValues } from "./actions/spec.js";
+import type { ImplementedAction } from "./actions/types.ts";
+import type { ActionPayload, ActionSpec, ContextState, ParsedIRIValues } from "./actions/spec.ts";
 export type ProcessActionArgs<State extends ContextState = ContextState, Spec extends ActionSpec<ContextState> = ActionSpec<ContextState>> = {
     iri: string;
     req: Request;

package/dist/processAction.js

@@ -1,4 +1,4 @@
-import { JsonPointer } from 'json-ptr';
+import { JsonPointer } from "json-ptr";
 import { getInternalName } from "./utils/getInternalName.js";
 import { getRequestBodyValues } from "./utils/getRequestBodyValues.js";
 import { getRequestIRIValues } from "./utils/getRequestIRIValues.js";