@occultist/occultist 0.0.4 → 0.0.6

package/lib/cache/cache.ts

@@ -1,8 +1,17 @@
 import {createHash} from 'node:crypto';
-import {CacheContext, NextFn, Registry} from '../mod.js';
-import {EtagConditions} from './etag.js';
-import type {CacheBuilder, CacheEntryDescriptor, CacheETagArgs, CacheETagInstanceArgs, CacheHitHandle, CacheHTTPArgs, CacheHTTPInstanceArgs, CacheMeta, CacheMissHandle, CacheStorage, CacheStoreArgs, CacheStoreInstanceArgs, LockedCacheMissHandle, UpstreamCache} from './types.js';
-
+import {CacheContext, type NextFn, Registry} from '../mod.ts';
+import {EtagConditions} from './etag.ts';
+import type {CacheBuilder, CacheEntryDescriptor, CacheETagArgs, CacheETagInstanceArgs, CacheHitHandle, CacheHTTPArgs, CacheHTTPInstanceArgs, CacheMeta, CacheMissHandle, CacheSemantics, CacheStorage, CacheStoreArgs, CacheStoreInstanceArgs, LockedCacheMissHandle, UpstreamCache} from './types.ts';
+
+const supportedSemantics: CacheSemantics[] = [
+  'options',
+  'head',
+  'get',
+  'post',
+  'put',
+  'delete',
+  'query',
+];
 
 export class Cache implements CacheBuilder {
   #registry: Registry;
@@ -74,8 +83,16 @@ export class Cache implements CacheBuilder {
 
   }
 
-  async invalidate(_req: Request): Promise<void> {
+  async invalidate(key: string, url: string): Promise<void> {
+    const promises = [
+      this.#cacheMeta.invalidate(key),
+      this.#storage.invalidate(key),
+    ];
+
+    if (this.#upstream != null)
+      promises.push(this.upstream.invalidate(url));
 
+    await Promise.all(promises);
   }
 }
 
@@ -103,10 +120,15 @@ export class CacheMiddleware {
       return false;
     });
 
-    if (descriptor == null) {
+    if (descriptor == null || !supportedSemantics.includes(descriptor.semantics)) {
       return await next();
     }
 
+    if (descriptor.semantics === 'put' || descriptor.semantics === 'delete') {
+      this.#useInvalidate(descriptor, ctx, next);
+      return;
+    }
+
     switch (descriptor.args.strategy) {
       case 'http': {
         await this.#useHTTP(descriptor, ctx, next);
@@ -126,22 +148,69 @@ export class CacheMiddleware {
   /**
    * @todo Implement vary rules.
    */
-  #makeKey(descriptor: CacheEntryDescriptor): string {
+  #makeKey(
+    descriptor: CacheEntryDescriptor,
+    ctx: CacheContext,
+  ): string {
+    const { authKey } = ctx;
     const { contentType } = descriptor;
     const { version } = descriptor.args;
     const { name } = descriptor.action;
     const { url } = descriptor.request;
 
-    return 'v' + (version ?? 0) + '|' + name + '|' + contentType.toLowerCase() + '|' + url.toString();
+    if (authKey == null)
+      return 'v' + (version ?? 0) + '|' + name + '|' + contentType.toLowerCase() + '|' + url.toString();
+    
+    return 'v' + (version ?? 0) + '|' + name + '|' + contentType.toLowerCase() + '|' + url.toString() + '|' + authKey;
   }
 
+
+  /**
+   * Sets response headers based of the cache args and authorization status.
+   */
   #setHeaders(
     descriptor: CacheEntryDescriptor,
     ctx: CacheContext,
   ): void {
-    const {
-      
-    } = descriptor.args;
+    const args = descriptor.args;
+    const cacheControl: string[] = [];
+
+    if (ctx.authKey != null && args.publicWhenAuthenticated) {
+      cacheControl.push('public');
+    } else if (ctx.authKey != null || args.private) {
+      cacheControl.push('private');
+    } else if (ctx.public) {
+      cacheControl.push('public');
+    }
+
+    if (cacheControl.length !== 0) {
+      ctx.headers.set('Cache-Control', cacheControl.join(', '));
+    }
+  }
+
+  /**
+   * Used for PUT and DELETE requests which should invalidate the cache
+   * when successful.
+   */
+  async #useInvalidate(
+    descriptor: CacheEntryDescriptor,
+    ctx: CacheContext,
+    next: NextFn,
+  ): Promise<void> {
+    await next();
+
+    if (ctx.status != null || ctx.status.toString()[0] !== '2') {
+      return;
+    }
+
+    const key = this.#makeKey(descriptor, ctx);
+    const args = descriptor.args;
+    const cache = args.cache;
+    
+    await cache.invalidate(
+      key,
+      ctx.url,
+    );
   }
 
   async #useHTTP(
@@ -159,10 +228,12 @@ export class CacheMiddleware {
     ctx: CacheContext,
     next: NextFn,
   ): Promise<void> {
-    const key = this.#makeKey(descriptor);
+    const key = this.#makeKey(descriptor, ctx);
     const rules = new EtagConditions(ctx.req.headers);
     const resourceState = await descriptor.args.cache.meta.get(key);
 
+    this.#setHeaders(descriptor, ctx);
+
     if (resourceState.type === 'cache-hit') {
       if (rules.ifMatch(resourceState.etag)) {
         return;
@@ -174,8 +245,6 @@ export class CacheMiddleware {
       }
     }
 
-    this.#setHeaders(descriptor, ctx);
-
     await next();
   }
 
@@ -184,50 +253,66 @@ export class CacheMiddleware {
     ctx: CacheContext,
     next: NextFn,
   ): Promise<void> {
-    const key = this.#makeKey(descriptor);
+    const key = this.#makeKey(descriptor, ctx);
     let resourceState:  CacheHitHandle | CacheMissHandle | LockedCacheMissHandle | undefined;
+    const args = descriptor.args;
+    const cache = args.cache;
 
-    if (
-      typeof descriptor.args.cache.meta.getOrLock === 'function' &&
-      descriptor.args.lock
-    ) {
-      try {
-        resourceState = await descriptor.args.cache.meta.getOrLock(key);
-      } catch (err) {
-        resourceState = await descriptor.args.cache.meta.get(key);
-      }
-    } else {
-      resourceState = await descriptor.args.cache.meta.get(key);
-    }
-
-    if (resourceState?.type === 'cache-hit') {
-      if (this.#isNotModified(ctx.req.headers, resourceState.etag)) {
-        ctx.hit = true;
-        ctx.status = 304;
+    this.#setHeaders(descriptor, ctx);
 
-        return;
+    if (descriptor.semantics === 'get' ||
+        descriptor.semantics === 'head' ||
+        descriptor.semantics === 'options' ||
+        descriptor.semantics === 'query'
+    ) {
+      if (
+        typeof cache.meta.getOrLock === 'function' &&
+        args.lock
+      ) {
+        try {
+          resourceState = await cache.meta.getOrLock(key);
+        } catch (err) {
+          resourceState = await cache.meta.get(key);
+        }
+      } else {
+        resourceState = await cache.meta.get(key);
       }
 
-      if (resourceState.hasContent) {
-        try {
+      if (resourceState?.type === 'cache-hit') {
+        if (this.#isNotModified(ctx.req.headers, resourceState.etag)) {
           ctx.hit = true;
-          ctx.status = resourceState.status;
-          ctx.body = await descriptor.args.cache.storage.get(key);
-
-          for (const [key, value] of resourceState.headers.entries()) {
-            ctx.headers.set(key, value);
-          }
+          ctx.status = 304;
 
           return;
-        } catch (err) {
-          console.log(err);
+        }
+
+        if (resourceState.hasContent) {
+          try {
+            ctx.hit = true;
+            ctx.status = resourceState.status;
+            ctx.body = await cache.storage.get(key);
+
+            for (const [key, value] of Object.entries(resourceState.headers)) {
+              if (Array.isArray(value)) {
+                ctx.headers.delete(key);
+
+                for (let i = 0; i < value.length; i++) {
+                  ctx.headers.append(key, value[i]);
+                }
+              } else {
+                ctx.headers.set(key, value);
+              }
+            }
+
+            return;
+          } catch (err) {
+            console.log(err);
+          }
         }
       }
     }
 
     try {
-      this.#setHeaders(descriptor, ctx);
-
       await next();
 
       const body = await new Response(ctx.body).blob();
@@ -236,19 +321,19 @@ export class CacheMiddleware {
       ctx.etag = etag;
       ctx.headers.set('Etag', etag);
 
-      await descriptor.args.cache.meta.set(key, {
+      await cache.meta.set(key, {
         key,
         authKey: ctx.authKey,
         iri: ctx.url,
         status: ctx.status ?? 200,
         hasContent: ctx.body != null,
-        headers: ctx.headers,
+        headers: Object.fromEntries(ctx.headers.entries()),
         contentType: ctx.contentType,
         etag,
       });
 
       if (ctx.body != null) {
-        await descriptor.args.cache.storage.set(key, body);
+        await cache.storage.set(key, body);
       }
 
       if (resourceState.type === 'locked-cache-miss') {
@@ -259,7 +344,6 @@ export class CacheMiddleware {
         ctx.hit = true;
         ctx.status = 304;
         ctx.body = null;
-        ctx.headers.delete('Etag');
         
         return;
       }
@@ -280,12 +364,14 @@ export class CacheMiddleware {
     return rules.isNotModified(etag);
   }
 
-  async #createEtag(body: Blob, weak: boolean = true): Promise<string> {
+  /**
+   * Creates a strong etag using a sha1 hashing algorithim.
+   */
+  async #createEtag(body: Blob): Promise<string> {
     const buff = await body.bytes();
     const hash = createHash('sha1').update(buff).digest('hex');
-    const quoted = `"${hash}"`;
 
-    return weak ? `W/${quoted}` : quoted;
+    return `"${hash}"`;
   }
 
 }

package/lib/cache/etag.test.ts

@@ -1,6 +1,6 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
-import {EtagConditions} from './etag.js';
+import {EtagConditions} from './etag.ts';
 
 
 test.describe('conditions.ifMatch()', () => {

package/lib/cache/file.ts

@@ -1,31 +1,49 @@
 import {createHash} from 'node:crypto';
-import type {CacheDetails, CacheHitHandle, CacheMeta, CacheStorage, CacheMissHandle} from './types.js';
-import {FileHandle, open, readFile, writeFile, rm} from 'node:fs/promises';
+import type {CacheDetails, CacheHitHandle, CacheMeta, CacheStorage, CacheMissHandle, UpstreamCache} from './types.ts';
+import {readFile, writeFile, rm} from 'node:fs/promises';
 import {join} from 'node:path';
+import {type FSWatcher, watchFile} from 'node:fs';
+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 class FileCacheMeta implements CacheMeta {
   
   #filePath: string;
-  #handle: FileHandle | undefined;
   #details: Record<string, CacheDetails> = {};
+  #watcher: FSWatcher | undefined;
+  #writing: boolean = false;
 
   constructor(filePath: string) {
     this.#filePath = filePath;
   }
 
   async #init(): Promise<void> {
-    this.#handle = await open(this.#filePath, 'w+');
-    const content = await this.#handle.readFile({ encoding: 'utf-8' });
+    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;
 
-    this.#details = JSON.parse(content);
+      const content = await readFile(this.#filePath, 'utf-8');
+      this.#details = JSON.parse(content);
+    }) as FSWatcher;
+    this.#watcher.unref();
   }
 
   async get(key: string): Promise<CacheHitHandle| CacheMissHandle> {
-    if (this.#handle == null) {
-      this.#init();
-    }
+    if (this.#watcher == null) await this.#init();
     
     const details = this.#details[key];
     async function set(details: CacheDetails) {
@@ -46,24 +64,69 @@ export class FileCacheMeta implements CacheMeta {
     };
   }
 
+  /**
+   * Sets a cached value.
+   *
+   * @param key Unique key for this cached value.
+   * @param details Details of the cache to store.
+   */
   async set(key: string, details: CacheDetails) {
+    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: string): Promise<void> {
+    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(): Promise<void> {
+    this.#details = {};
+    await this.#write();
+  }
+
+  async #write(): Promise<void> {
+    this.#writing = true;
+    
+    try {
+      await writeFile(this.#filePath, JSON.stringify(this.#details));
+    } catch {}
+
+    this.#writing = false;
+  }
 }
 
 export class FileSystemCacheStorage implements CacheStorage {
 
   #directory: string;
   #hashes: Map<string, string> = new Map();
+
+  constructor(directory: string) {
+    this.#directory = directory;
+  }
   
   hash(key: string): string {
     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);
 
@@ -83,4 +146,42 @@ export class FileSystemCacheStorage implements CacheStorage {
   async invalidate(key: string): Promise<void> {
     await rm(join(this.#directory, this.hash(key)));
   }
+
+  async flush(): Promise<void> {
+    const promises: Array<Promise<void>> = [];
+
+    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: FileCacheMeta;
+  #fileSystemStorage: FileSystemCacheStorage;
+
+  constructor(registry: Registry, filePath: string, directory: string, upstream?: UpstreamCache) {
+    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/lib/cache/memory.ts

@@ -1,10 +1,18 @@
-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 class InMemoryCacheMeta implements CacheMeta {
   #details: Map<string, CacheDetails> = new Map();
+  #locks: Map<string, Promise<void>> = new Map();
+  #flushLock: Promise<void> | undefined;
+
+  async get(key: string): Promise<CacheHitHandle | CacheMissHandle> {
+    if (this.#flushLock) {
+      await this.#flushLock;
+    }
 
-  async get(key: string): Promise<CacheHitHandle| CacheMissHandle> {
     const details = this.#details.get(key);
     async function set(details: CacheDetails) {
       this.#details.set(key, details);
@@ -24,10 +32,67 @@ export class InMemoryCacheMeta implements CacheMeta {
     };
   }
 
-  async set(key: string, details: CacheDetails) {
+  set(key: string, details: CacheDetails): void {
     this.#details.set(key, details);
   }
 
+  async getOrLock(key: string): Promise<CacheHitHandle | LockedCacheMissHandle> {
+    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<void>();
+
+    this.#locks.set(key, promise);
+    
+    function set(details: CacheDetails) {
+      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: string): void {
+    this.#details.delete(key);
+  }
+
+  async flush(): Promise<void> {
+    const { resolve, promise } = Promise.withResolvers<void>();
+    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 implements CacheStorage {
@@ -47,6 +112,23 @@ export class InMemoryCacheStorage implements CacheStorage {
     this.#cache.delete(key);
   }
 
+  flush(): void {
+    this.#cache = new Map();
+  }
 }
 
+export class InMemoryCache extends Cache {
+  constructor(registry: Registry, upstream?: UpstreamCache) {
+    super(
+      registry,
+      new InMemoryCacheMeta(),
+      new InMemoryCacheStorage(),
+      upstream,
+    );
+  }
 
+  async flush() {
+    await this.meta.flush();
+    this.storage.flush();
+  }
+}