@occultist/occultist 0.0.1

package/lib/actions/writer.test.ts

@@ -0,0 +1,57 @@
+import {createServer} from 'node:http';
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {ResponseWriter} from './writer.js';
+import {AddressInfo} from 'node:net';
+
+
+test('Writer writes hints', () => {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+
+    server.on('request', async (_req, res) => {
+      const writer = new ResponseWriter(res);
+      await writer.writeEarlyHints({
+        link: [
+          {
+            href: 'https://example.com/main.css',
+            as: 'stylesheet',
+            preload: true,
+            fetchPriority: 'high',
+          },
+          {
+            href: 'https://example.com/main.js',
+            as: 'script',
+            preload: true,
+            fetchPriority: 'low',
+          }
+        ],
+      });
+
+      writer.writeHead(200);
+
+      res.end();
+    });
+
+    server.on('error', (err) => {
+      reject(err);
+    });
+  
+    server.listen(0, '127.0.0.1', async () => {
+      const { port, address } = server.address() as AddressInfo;
+  
+      const res = await fetch(`http://${address}:${port}`);
+      await res.text();
+
+      assert(
+        res.headers.get('link'),
+        `</https://example.com/main.css>; rel=preload; as=stylesheet; fetchpriority=high, `
+        + `</https://example.com/main.js>; rel=preload; as=script; fetchpriority=low`,
+      );
+
+      server.close();
+
+      resolve();
+    });
+  });
+});

package/lib/actions/writer.ts

@@ -0,0 +1,176 @@
+import { ServerResponse } from 'node:http';
+import type { HintLink, HintArgs, HintObj } from './types.js';
+
+
+function isHintLink(hint: HintObj | HintLink): hint is HintLink {
+  return hint.href != null;
+}
+
+export type ResponseTypes =
+  | ServerResponse
+  | Response
+;
+
+export type ResponseBody = BodyInit;
+
+
+export interface HTTPWriter {
+  mergeHeaders(headers: HeadersInit): void;
+  writeEarlyHints(args: HintArgs): void;
+  mergeHeaders(headers: HeadersInit): void;
+  writeHead(status: number, headers?: Headers): void;
+  writeBody(body: ResponseBody): void;
+  response(): ResponseTypes;
+};
+
+export class ResponseWriter implements HTTPWriter {
+  #res?: ServerResponse;
+  #hints?: {
+    link: string | string[];
+  };
+  #status?: number;
+  #statusText?: string;
+  #headers: Headers = new Headers();
+  #body?: ResponseBody;
+
+  constructor(
+    res?: ServerResponse,
+  ) {
+    this.#res = res;
+  }
+
+  /**
+   * Writes early hints to the request.
+   *
+   * Runtimes which do not support writing early hints will have the
+   * headers added to the headers of the main response instead.
+   */
+  writeEarlyHints(args: HintArgs): Promise<void> {
+    const links: string[] = []
+    
+    if (Array.isArray(args)) {
+      for (let i = 0; i < args.length; i++) {
+        links.push(this.#formatEarlyHint(args[i]));
+      }
+    } else if (typeof args === 'function') {
+      const res = args();
+
+      if (Array.isArray(res)) {
+        for (let i = 0; i < res.length; i++) {
+          links.push(this.#formatEarlyHint(res[i]))
+        }
+      } else if (isHintLink(res)) {
+        links.push(this.#formatEarlyHint(res));
+      } else if (Array.isArray(res.link)) {
+        for (let i = 0; i < res.link.length; i++) {
+          links.push(this.#formatEarlyHint(res.link[i]));
+        }
+      } else {
+        links.push(this.#formatEarlyHint(res.link));
+      }
+    } else if (isHintLink(args)) {
+      links.push(this.#formatEarlyHint(args));
+    } else if (Array.isArray(args.link)) {
+      for (let i = 0; i < args.link.length; i++) {
+        links.push(this.#formatEarlyHint(args.link[i]));
+      }
+    } else {
+      links.push(this.#formatEarlyHint(args.link));
+    }
+
+    if (this.#res == null) {
+      this.#headers.append('Link', links.join(', '));
+    } else {
+      return new Promise((resolve) => {
+        this.#res.writeEarlyHints({ 'Link': links.join(', ') }, resolve);
+      });
+    }
+  }
+
+  mergeHeaders(headersInit: HeadersInit): void {
+    this.#setHeaders(new Headers(headersInit));
+  }
+
+  writeHead(status: number, headers?: Headers) {
+    const res = this.#res;
+
+    this.#status = status;
+   
+    if (headers != null) {
+      this.#setHeaders(headers);
+    }
+
+    if (res instanceof ServerResponse && this.#hints != null) {
+      res.writeHead(status, this.#hints);
+    } else if (res instanceof ServerResponse) {
+      res.writeHead(status);
+    }
+  }
+
+  writeBody(body: ResponseBody): void {
+    if (this.#res instanceof ServerResponse) {
+      this.#res.write(body);
+    } else {
+      this.#body = body;
+    }
+  }
+
+  response(): Response | ServerResponse {
+    if (this.#res instanceof ServerResponse) {
+      this.#res.end();
+      
+      return this.#res;
+    }
+    
+    if (this.#body instanceof Uint8Array) {
+    }
+
+    return new Response(this.#body as BodyInit, {
+      status: this.#status,
+      statusText: this.#statusText,
+      headers: this.#headers,
+    });
+  }
+
+  #setHeaders(headers: Headers): void {
+    for (const [header, value] of headers.entries()) {
+      if (Array.isArray(value)) {
+        for (const item of value) {
+          this.#headers.append(header, item);
+        }
+      } else {
+        this.#headers.append(header, value);
+      }
+    }
+  }
+
+  #formatEarlyHint(hint: HintLink): string {
+    let link: string = `<${encodeURI(hint.href)}>`;
+
+    if (hint.preload) {
+      link += `; rel=preload`;
+    }
+
+    if (Array.isArray(hint.rel)) {
+      link += '; ' + hint.rel.map((rel) => `rel=${rel}`)
+        .join('; ') + '';
+    } else if (hint.rel != null) {
+      link += `; rel=${hint.rel}`;
+    }
+      
+    if (hint.as != null) {
+      link += `; as=${hint.as}`;
+    }
+
+    if (hint.fetchPriority != null) {
+      link += `; fetchpriority=${hint.fetchPriority}`;
+    }
+
+    if (hint.crossOrigin != null) {
+      link += `; crossorigin=${hint.crossOrigin}`;
+    }
+
+    return link;
+  }
+
+}

package/lib/auth/types.ts

@@ -0,0 +1,22 @@
+
+export type UnauthenticatedAuthContext = {
+  authenticated: false;
+  authKey: undefined;
+};
+
+export type AuthenticatedAuthContext = {
+  authenticated: true;
+  authKey: string;
+};
+
+// deno-lint-ignore no-explicit-any
+export type AuthState = Record<string, any>;
+
+export type AuthMiddlewareResponse<
+  State extends AuthState = AuthState,
+> = {
+  authKey?: string;
+  allowPublic?: boolean;
+  state: State;
+};
+

package/lib/cache/cache.ts

@@ -0,0 +1,291 @@
+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';
+
+
+export class Cache implements CacheBuilder {
+  #registry: Registry;
+  #cacheMeta: CacheMeta;
+  #storage: CacheStorage;
+  #upstream?: UpstreamCache;
+
+  constructor(
+    registry: Registry,
+    cacheMeta: CacheMeta,
+    storage: CacheStorage,
+    upstream?: UpstreamCache,
+  ) {
+    this.#registry = registry;
+    this.#cacheMeta = cacheMeta;
+    this.#storage = storage;
+    this.#upstream = upstream;
+  }
+
+  get registry(): Registry {
+    return this.#registry;
+  }
+
+  get meta(): CacheMeta {
+    return this.#cacheMeta;
+  }
+
+  get storage(): CacheStorage {
+    return this.#storage;
+  }
+
+  get upstream(): UpstreamCache {
+    return this.#upstream;
+  }
+
+  /**
+   * Add HTTP headers to the request.
+   */
+  http(args?: CacheHTTPArgs): CacheHTTPInstanceArgs {
+    return Object.assign(Object.create(null), args, {
+      strategy: 'http',
+      cache: this,
+    });
+  }
+
+  /**
+   * Stores an etag value of the response and adds HTTP headers to the request.
+   * Requests made to an endpoint implementing etag cache can use `If-None-Match`
+   * or `If-Modified-Since` headers to test 
+   */
+  etag(args?: CacheETagArgs): CacheETagInstanceArgs {
+    return Object.assign(Object.create(null), args, {
+      strategy: 'etag',
+      cache: this,
+    });
+  }
+
+  /**
+   * Caches the body of the response, stores and etag and adds HTTP headers to the request.
+   */
+  store(args?: CacheStoreArgs): CacheStoreInstanceArgs {
+    return Object.assign(Object.create(null), args, {
+      strategy: 'store',
+      cache: this,
+    });
+  }
+
+  async push(_req: Request): Promise<void> {
+
+  }
+
+  async invalidate(_req: Request): Promise<void> {
+
+  }
+}
+
+export class CacheMiddleware {
+  async use(
+    descriptors: CacheEntryDescriptor[],
+    ctx: CacheContext,
+    next: NextFn,
+  ): Promise<void> {
+    const descriptor = descriptors.find((descriptor) => {
+      const when = descriptor.args.when;
+
+      if (when == null) {
+        return true;
+      } else if (when === 'always') {
+        return true;
+      } else if (when === 'public' && ctx.authKey == null) {
+        return true;
+      } else if (when === 'private' && ctx.authKey != null) {
+        return true;
+      } else if (typeof when === 'function') {
+        return when(ctx);
+      }
+
+      return false;
+    });
+
+    if (descriptor == null) {
+      return await next();
+    }
+
+    switch (descriptor.args.strategy) {
+      case 'http': {
+        await this.#useHTTP(descriptor, ctx, next);
+        break;
+      }
+      case 'etag': {
+        await this.#useEtag(descriptor, ctx, next);
+        break;
+      }
+      case 'store': {
+        await this.#useStore(descriptor, ctx, next);
+        break;
+      }
+    }
+  }
+
+  /**
+   * @todo Implement vary rules.
+   */
+  #makeKey(descriptor: CacheEntryDescriptor): string {
+    const { contentType } = descriptor;
+    const { version } = descriptor.args;
+    const { name } = descriptor.action;
+    const { url } = descriptor.request;
+
+    return 'v' + (version ?? 0) + '|' + name + '|' + contentType.toLowerCase() + '|' + url.toString();
+  }
+
+  #setHeaders(
+    descriptor: CacheEntryDescriptor,
+    ctx: CacheContext,
+  ): void {
+    const {
+      
+    } = descriptor.args;
+  }
+
+  async #useHTTP(
+    descriptor: CacheEntryDescriptor,
+    ctx: CacheContext,
+    next: NextFn,
+  ): Promise<void> {
+    this.#setHeaders(descriptor, ctx);
+
+    await next();
+  }
+
+  async #useEtag(
+    descriptor: CacheEntryDescriptor,
+    ctx: CacheContext,
+    next: NextFn,
+  ): Promise<void> {
+    const key = this.#makeKey(descriptor);
+    const rules = new EtagConditions(ctx.req.headers);
+    const resourceState = await descriptor.args.cache.meta.get(key);
+
+    if (resourceState.type === 'cache-hit') {
+      if (rules.ifMatch(resourceState.etag)) {
+        return;
+      } else if (!rules.ifNoneMatch(resourceState.etag)) {
+        ctx.hit = true;
+        ctx.status = 304;
+
+        return
+      }
+    }
+
+    this.#setHeaders(descriptor, ctx);
+
+    await next();
+  }
+
+  async #useStore(
+    descriptor: CacheEntryDescriptor,
+    ctx: CacheContext,
+    next: NextFn,
+  ): Promise<void> {
+    const key = this.#makeKey(descriptor);
+    let resourceState:  CacheHitHandle | CacheMissHandle | LockedCacheMissHandle | undefined;
+
+    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;
+
+        return;
+      }
+
+      if (resourceState.hasContent) {
+        try {
+          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);
+          }
+
+          return;
+        } catch (err) {
+          console.log(err);
+        }
+      }
+    }
+
+    try {
+      this.#setHeaders(descriptor, ctx);
+
+      await next();
+
+      const body = await new Response(ctx.body).blob();
+      const etag = await this.#createEtag(body);
+
+      ctx.etag = etag;
+      ctx.headers.set('Etag', etag);
+
+      await descriptor.args.cache.meta.set(key, {
+        key,
+        authKey: ctx.authKey,
+        iri: ctx.url,
+        status: ctx.status ?? 200,
+        hasContent: ctx.body != null,
+        headers: ctx.headers,
+        contentType: ctx.contentType,
+        etag,
+      });
+
+      if (ctx.body != null) {
+        await descriptor.args.cache.storage.set(key, body);
+      }
+
+      if (resourceState.type === 'locked-cache-miss') {
+        await resourceState.release();
+      }
+
+      if (this.#isNotModified(ctx.req.headers, etag)) {
+        ctx.hit = true;
+        ctx.status = 304;
+        ctx.body = null;
+        ctx.headers.delete('Etag');
+        
+        return;
+      }
+    } catch (err) {
+      if (resourceState.type === 'locked-cache-miss') {
+        await resourceState.release();
+      }
+    }
+  }
+
+  /**
+   * Returns true if the request has conditional headers
+   * which should result in a not modified response.
+   */
+  #isNotModified(headers: Headers, etag: string): boolean {
+    const rules = new EtagConditions(headers);
+
+    return rules.isNotModified(etag);
+  }
+
+  async #createEtag(body: Blob, weak: boolean = true): Promise<string> {
+    const buff = await body.bytes();
+    const hash = createHash('sha1').update(buff).digest('hex');
+    const quoted = `"${hash}"`;
+
+    return weak ? `W/${quoted}` : quoted;
+  }
+
+}

package/lib/cache/etag.test.ts

@@ -0,0 +1,122 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import {EtagConditions} from './etag.js';
+
+
+test.describe('conditions.ifMatch()', () => {
+  test('returns true when the header has the value of "*" and an etag is present', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-Match': '*',
+    }));
+  
+    assert(conditions.ifMatch('"xxxx"'));
+  });
+
+  test('returns false when the header has the value of "*" and an etag is not present', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-Match': '*',
+    }));
+  
+    assert(!conditions.ifMatch());
+  });
+
+  test('returns false when the header provides an etag and an etag is not present', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-Match': '"xxxx"',
+    }));
+  
+    assert(!conditions.ifMatch());
+  });
+
+  test('returns false when the header provides an etag and a different etag is present', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-Match': '"xxxx"',
+    }));
+  
+    assert(!conditions.ifMatch('"yyyy"'));
+  });
+
+  test('returns false when the header provides a matching but weak etag', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-Match': 'W\/"xxxx"',
+    }));
+  
+    assert(!conditions.ifMatch('W\/"xxxx"'));
+  });
+
+  test('returns true when the header provides a matching etag', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-Match': '"xxxx"',
+    }));
+  
+    assert(conditions.ifMatch('"xxxx"'));
+  });
+
+  test('returns true when the header provides a list containing a matching etag', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-Match': '"xxxx", "yyyy", "zzzz"',
+    }));
+  
+    assert(conditions.ifMatch('"yyyy"'));
+  });
+});
+
+
+test.describe('conditions.ifNoneMatch()', () => {
+  test('returns true when the header has the value of "*" and an etag is not present', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-None-Match': '*',
+    }));
+  
+    assert(conditions.ifNoneMatch());
+  });
+
+  test('returns false when the header has the value of "*" and an etag is present', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-None-Match': '*',
+    }));
+  
+    assert(!conditions.ifNoneMatch('W\/"xxxx"'));
+  });
+
+  test('returns true when the header provides an etag and no representation etag is present', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-None-Match': 'W\/"xxxx"',
+    }));
+  
+    assert(conditions.ifNoneMatch());
+  });
+
+  test('returns true when the header provides a non-matching etag', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-None-Match': 'W\/"xxxx"',
+    }));
+  
+    assert(conditions.ifNoneMatch('W\/"yyyy"'));
+  });
+
+  test('returns true when the header provides a non-matching but strong etag', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-None-Match': '"yyyy"',
+    }));
+  
+    assert(conditions.ifNoneMatch('"xxxx"'));
+  });
+
+  test('returns false when the header provides a matching etag', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-None-Match': 'W\/"xxxx"',
+    }));
+  
+    assert(!conditions.ifNoneMatch('W\/"xxxx"'));
+  });
+
+  test('returns false when the header provides a list containing a matching etag', () => {
+    const conditions = new EtagConditions(new Headers({
+      'If-None-Match': 'W\/"xxxx", W\/"yyyy", W\/"zzzz"',
+    }));
+  
+    assert(!conditions.ifNoneMatch('W\/"yyyy"'));
+  });
+});
+