@global-cache/core 0.2.3

package/src/client/index.ts

@@ -0,0 +1,137 @@
+import { globalConfig, GlobalCacheConfig } from '../config';
+import { debug, debugKey } from '../shared/debug';
+import { logger } from '../shared/logger';
+import { calcSignature } from '../shared/sig';
+import { StorageApi } from './api';
+import { DefaultKeysSchema, GetArgs, StringKeys } from './types';
+import { previewValue } from './utils/preview-value';
+
+export { DefaultKeysSchema };
+
+export class GlobalCacheClient<S extends DefaultKeysSchema = DefaultKeysSchema> {
+  #api?: StorageApi;
+
+  /*
+   * Helper method to set global config via storage instance (for conveniency)
+   */
+  config(config: GlobalCacheConfig) {
+    globalConfig.update(config);
+  }
+
+  private get api() {
+    if (!this.#api) {
+      const { serverUrl, runId } = globalConfig;
+      if (!serverUrl) {
+        throw new Error('Global-cache url is empty. Did you run the global-cache setup?');
+      }
+      this.#api = new StorageApi(serverUrl, runId);
+    }
+    return this.#api;
+  }
+
+  /**
+   * Get value by key or compute it if not found.
+   */
+  // eslint-disable-next-line visual/complexity, max-statements
+  async get<K extends StringKeys<S>>(...args: GetArgs<K, S>): Promise<S[K]> {
+    const { key, params, fn } = resolveGetArgs(args);
+
+    if (globalConfig.disabled) {
+      debugKey(key, `Global cache disabled. Computing...`);
+      return fn();
+    }
+
+    const ttl = globalConfig.ignoreTTL ? undefined : params.ttl;
+
+    // keep stack expression in this fn to have correct stack offset
+    const stack = new Error().stack?.split('\n')[2]?.trim().replace(process.cwd(), '') || '';
+    const sig = calcSignature({ fn, ttl, stack });
+
+    debugKey(key, `Fetching value...`);
+    const body = await this.api.get({ key, sig, ttl });
+
+    if (body.result === 'cache-hit') {
+      const { value } = body.valueInfo;
+      debugKey(key, `${body.result}: ${previewValue(value)}`);
+      return value as S[K];
+    }
+
+    if (body.result === 'error') {
+      throw new Error(body.message);
+    }
+
+    if (body.result === 'sig-mismatch') {
+      logger.warn(body.message);
+      debugKey(key, `${body.result}, computing...`);
+    } else {
+      debugKey(key, `${body.result} (${body.message}), computing...`);
+    }
+
+    const { value, error } = await this.computeValue(fn);
+    debugKey(key, error ? `Error: ${error.message}` : `Computed: ${previewValue(value)}`);
+
+    if (body.result === 'sig-mismatch') {
+      debugKey(key, `Not saving value because of signature mismatch.`);
+      if (error) throw error;
+      return value;
+    }
+
+    debugKey(key, `Saving value...`);
+    const valueInfo = await this.api.set({ key, value, error });
+    debugKey(key, `Saved.`);
+
+    if (error) throw error;
+
+    // We return 'valueInfo.value' instead of 'value' to have exact the same value
+    // as stored (in case of serialization changes).
+    return valueInfo.value as S[K];
+  }
+
+  /**
+   * Fetch stale value.
+   * - for non-persistant keys it would be the current value
+   * - for persistent keys it would be the old value if it was changed during this run
+   */
+  async getStale<K extends StringKeys<S>>(key: K) {
+    debugKey(key, `Fetching stale value...`);
+    const value = await this.api.getStale({ key });
+    debugKey(key, `Fetched: ${previewValue(value)}`);
+
+    return value as S[K] | undefined;
+  }
+
+  /**
+   * Fetch list of stale values by prefix.
+   * - for non-persistant keys it would be the current value
+   * - for persistent keys it would be the old value if it was changed during this run
+   */
+  async getStaleList<ValueType>(prefix: string) {
+    debugKey(prefix, `Fetching stale list...`);
+    const values = await this.api.getStaleList({ prefix });
+    debugKey(prefix, `Fetched: ${values.length} value(s)`);
+
+    return values as ValueType[];
+  }
+
+  async clear() {
+    debug('Clearing test-run values...');
+    await this.api.clear();
+    debug('Cleared.');
+  }
+
+  private async computeValue<ValueType>(fn: () => ValueType) {
+    try {
+      const value = await fn();
+      return { value };
+    } catch (e) {
+      const error = e instanceof Error ? e : new Error(String(e));
+      return { error };
+    }
+  }
+}
+
+function resolveGetArgs<K extends StringKeys<S>, S extends DefaultKeysSchema>(args: GetArgs<K, S>) {
+  return args.length === 2
+    ? { key: args[0], params: {}, fn: args[1] }
+    : { key: args[0], params: { ...args[1] }, fn: args[2] };
+}

package/src/client/types.ts

@@ -0,0 +1,14 @@
+/**
+ * Helper types.
+ */
+import { TTL } from '../shared/ttl';
+
+// Key-value types for strictly typed storage.
+export type DefaultKeysSchema = Record<string, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
+export type StringKeys<S extends DefaultKeysSchema> = keyof S & string; // strip number | symbol;
+
+export type ComputeFn<Res> = () => Res | Promise<Res>;
+export type KeyParams = { ttl?: TTL };
+export type GetArgs<K extends StringKeys<S>, S extends DefaultKeysSchema> =
+  | [K, ComputeFn<S[K]>]
+  | [K, KeyParams, ComputeFn<S[K]>];

package/src/client/utils/http-error.ts

@@ -0,0 +1,8 @@
+export async function buildHttpError(res: Response, prefix: string) {
+  const message = (await res.text()) || `${res.status} ${res.statusText}`;
+  return new Error(`${prefix} ${message}`);
+}
+
+export async function throwIfHttpError(res: Response, message: string) {
+  if (!res.ok) throw await buildHttpError(res, message);
+}

package/src/client/utils/http-json.ts

@@ -0,0 +1,32 @@
+/**
+ * Simple http client for json payloads.
+ */
+
+import { addSearchParams } from './http-query';
+
+const headers = { 'Content-Type': 'application/json' };
+
+export type QueryParams<T extends Record<string, unknown>> = {
+  [K in keyof T]: string;
+};
+
+export class HttpJson {
+  constructor(private baseUrl: string) {}
+
+  async get(pathname: string, query?: Record<string, string>) {
+    const url = this.buildUrl(pathname, query);
+    return fetch(url, { method: 'GET', headers });
+  }
+
+  async post(pathname: string, bodyObj?: Record<string, unknown>) {
+    const url = this.buildUrl(pathname);
+    const body = bodyObj ? JSON.stringify(bodyObj) : undefined;
+    return fetch(url, { method: 'POST', headers, body });
+  }
+
+  buildUrl(pathname: string, query?: Record<string, string>) {
+    const url = new URL(pathname, this.baseUrl);
+    addSearchParams(url, query);
+    return url.toString();
+  }
+}

package/src/client/utils/http-query.ts

@@ -0,0 +1,24 @@
+import { QueryParams } from './http-json';
+
+export function addSearchParams(url: URL, query?: Record<string, string>) {
+  const preparedQuery = prepareQueryParams(query || {});
+  Object.entries(preparedQuery).forEach(([key, value]) => {
+    url.searchParams.append(key, String(value));
+  });
+}
+
+/**
+ * Converts record of parameters to query string format.
+ * - undefined values are ignored
+ * - values are converted to strings
+ */
+export function prepareQueryParams<T extends Record<string, unknown>>(params?: T): QueryParams<T> {
+  const query: QueryParams<T> = {} as QueryParams<T>;
+  Object.entries(params || {}).forEach(([key, value]) => {
+    if (value !== undefined) {
+      query[key as keyof T] = String(value);
+    }
+  });
+
+  return query;
+}

package/src/client/utils/preview-value.ts

@@ -0,0 +1,10 @@
+export function previewValue(value: unknown) {
+  try {
+    if (value === undefined) return '<undefined>';
+    const strValue = JSON.stringify(value);
+    return strValue.length > 50 ? `${strValue.slice(0, 50)}...` : strValue;
+  } catch {
+    // Fallback for non-serializable values
+    return `<non-serializable>`;
+  }
+}

package/src/config.ts

@@ -0,0 +1,79 @@
+/**
+ * Global config is shared across host and all workers via env variables.
+ * Assumption here is that all runners start workers with the same env.
+ */
+import { randomUUID } from 'node:crypto';
+import { removeUndefined } from './shared/utils/object';
+
+export type GlobalCacheConfig = {
+  /* Forces all values to be non-persistent, usefull for CI */
+  ignoreTTL?: boolean;
+  /* Where to store files, ignored if serverUrl is set */
+  basePath?: string;
+  /* Disables global storage, all values will be computed each time */
+  disabled?: boolean;
+  /* External server url */
+  serverUrl?: string;
+};
+
+type GlobalConfigInternal = GlobalCacheConfig & {
+  serverUrl: string;
+  runId: string;
+};
+
+export class GlobalConfig {
+  private config: GlobalConfigInternal = {
+    serverUrl: '', // will be set later, when server starts.
+    runId: '', // will be set later
+  };
+
+  constructor() {
+    Object.assign(this.config, getConfigFromEnv());
+    if (!this.runId) this.newTestRun();
+  }
+
+  update(config: Partial<GlobalConfigInternal>) {
+    Object.assign(this.config, removeUndefined(config));
+    saveConfigToEnv(this.config);
+  }
+
+  /**
+   * Generate new runId or re-use from env variable.
+   * There can be multiple test runs within single server session.
+   */
+  newTestRun() {
+    this.update({ runId: process.env.GLOBAL_CACHE_RUN_ID || randomUUID() });
+  }
+
+  get serverUrl() {
+    return this.config.serverUrl;
+  }
+
+  get ignoreTTL() {
+    return Boolean(this.config.ignoreTTL);
+  }
+
+  get basePath() {
+    return this.config.basePath;
+  }
+
+  get disabled() {
+    return Boolean(this.config.disabled);
+  }
+
+  get runId() {
+    return this.config.runId;
+  }
+}
+
+function getConfigFromEnv() {
+  const configFromEnv = process.env.GLOBAL_STORAGE_CONFIG;
+  return configFromEnv ? (JSON.parse(configFromEnv) as GlobalCacheConfig) : undefined;
+}
+
+function saveConfigToEnv(config: GlobalCacheConfig) {
+  process.env.GLOBAL_STORAGE_CONFIG = JSON.stringify(config);
+}
+
+/* Export singleton instance */
+export const globalConfig = new GlobalConfig();

package/src/index.ts

@@ -0,0 +1,2 @@
+export { GlobalCacheClient, DefaultKeysSchema } from './client/index.js';
+export { globalConfig, GlobalCacheConfig } from './config.js';

package/src/server/config.ts

@@ -0,0 +1,29 @@
+/**
+ * Global storage server configuration.
+ */
+import { Express } from 'express';
+import { removeUndefined } from '../shared/utils/object';
+
+export type GlobalCacheServerConfig = {
+  port?: number;
+  basePath?: string;
+  multiInstance?: boolean;
+};
+
+const defaults: Pick<Required<GlobalCacheServerConfig>, 'basePath'> = {
+  basePath: '.global-cache',
+};
+
+export type GlobalCacheServerConfigResolved = ReturnType<typeof buildResolvedConfig>;
+
+export function setConfig(app: Express, providedConfig: GlobalCacheServerConfig) {
+  app.locals.config = buildResolvedConfig(providedConfig);
+}
+
+export function getConfig(app: Express) {
+  return app.locals.config as GlobalCacheServerConfigResolved;
+}
+
+function buildResolvedConfig(providedConfig: GlobalCacheServerConfig) {
+  return Object.assign({}, defaults, removeUndefined(providedConfig));
+}

package/src/server/error.ts

@@ -0,0 +1,7 @@
+import { Request, Response, NextFunction } from 'express';
+
+// eslint-disable-next-line max-params
+export function errorHandler(err: unknown, _req: Request, res: Response, _next: NextFunction) {
+  const message = (err as Error)?.message || String(err);
+  res.status(500).send(message);
+}

package/src/server/getter.ts

@@ -0,0 +1,138 @@
+/**
+ * Handles "get" request for single-instance storage.
+ */
+import { checkSignature, SignatureMismatch } from '../shared/sig';
+import { isExpired } from '../shared/ttl';
+import { TestRunValueInfo } from '../shared/value-info';
+import { IPersistentStorage, ITestRunStorage } from './storage/types';
+
+type GetterCacheMiss = { result: 'cache-miss'; message: string };
+type GetterCacheHit = { result: 'cache-hit'; valueInfo: TestRunValueInfo };
+type GetterError = { result: 'error'; message: string };
+type GetterSingatureMismatch = { result: 'sig-mismatch'; message: string };
+
+export type GetterResult = GetterCacheMiss | GetterCacheHit | GetterError | GetterSingatureMismatch;
+
+export class Getter {
+  constructor(
+    private testRunStorage: ITestRunStorage,
+    private persistentStorage: IPersistentStorage,
+  ) {}
+
+  // eslint-disable-next-line visual/complexity, max-statements
+  async get(key: string, sig: string, ttl?: number): Promise<GetterResult> {
+    let valueInfo = await this.testRunStorage.load(key);
+
+    // check signature (for already accessed value)
+    if (valueInfo) {
+      const signatureMismatch = checkSignature(key, valueInfo.sig, sig);
+      if (signatureMismatch) {
+        return this.handleSignatureMismatch(key, signatureMismatch);
+      }
+    }
+
+    // wait if computing
+    if (valueInfo?.state === 'computing') {
+      valueInfo = await this.testRunStorage.wait(key);
+      return valueInfo.state === 'computed'
+        ? this.handleComputed(valueInfo)
+        : this.handleError(valueInfo);
+    }
+
+    // load from persistent storage
+    if (!valueInfo && ttl) {
+      valueInfo = await this.persistentStorage.load(key);
+      if (valueInfo) {
+        const signatureMismatch = checkSignature(key, valueInfo.sig, sig);
+        // eslint-disable-next-line max-depth
+        if (signatureMismatch) {
+          return this.handleSignatureChanged(valueInfo, sig, signatureMismatch);
+        }
+      }
+    }
+
+    // check expired
+    if (valueInfo?.state === 'computed' && valueInfo.persistent && ttl) {
+      if (isExpired(valueInfo.computedAt, ttl)) {
+        return this.handleExpired(valueInfo, ttl);
+      }
+    }
+
+    // normal cache hit
+    if (valueInfo?.state === 'computed') {
+      return this.handleComputed(valueInfo);
+    }
+
+    // no value
+    if (!valueInfo) {
+      return this.handleNoValue(key, sig, ttl);
+    }
+
+    return this.handleDefault(valueInfo);
+  }
+
+  private handleSignatureMismatch(
+    key: string,
+    signatureMismatch: SignatureMismatch,
+  ): GetterSingatureMismatch {
+    return { result: 'sig-mismatch', message: buildSignatureError(key, signatureMismatch) };
+  }
+
+  private handleComputed(valueInfo: TestRunValueInfo): GetterCacheHit {
+    return { result: 'cache-hit', valueInfo };
+  }
+
+  private handleError(valueInfo: TestRunValueInfo): GetterError {
+    return { result: 'error', message: valueInfo.errorMessage || 'Unknown error' };
+  }
+
+  private async handleSignatureChanged(
+    loadedValueInfo: TestRunValueInfo,
+    newSig: string,
+    { field }: SignatureMismatch,
+  ): Promise<GetterCacheMiss> {
+    await this.updateValueInfo(loadedValueInfo, {
+      state: 'computing',
+      sig: newSig,
+      prevValue: loadedValueInfo.value,
+      value: undefined,
+      computedAt: undefined,
+    });
+    return { result: 'cache-miss', message: `signature changed: ${field}` };
+  }
+
+  private async handleExpired(valueInfo: TestRunValueInfo, ttl: number): Promise<GetterCacheMiss> {
+    await this.updateValueInfo(valueInfo, {
+      state: 'computing',
+      prevValue: valueInfo.value,
+      value: undefined,
+      computedAt: undefined,
+    });
+    return { result: 'cache-miss', message: `expired: ${ttl}` };
+  }
+
+  private async handleNoValue(key: string, sig: string, ttl?: number): Promise<GetterCacheMiss> {
+    await this.updateValueInfo({ key, state: 'computing', sig, persistent: Boolean(ttl) });
+    return { result: 'cache-miss', message: 'no cached value' };
+  }
+
+  private async handleDefault(valueInfo: TestRunValueInfo): Promise<GetterCacheMiss> {
+    const message = `old state: ${valueInfo.state}`;
+    await this.updateValueInfo(valueInfo, { state: 'computing' });
+    return { result: 'cache-miss', message };
+  }
+
+  private async updateValueInfo(valueInfo: TestRunValueInfo, props?: Partial<TestRunValueInfo>) {
+    Object.assign(valueInfo, props);
+    await this.testRunStorage.save(valueInfo);
+  }
+}
+
+function buildSignatureError(key: string, { field, value1, value2 }: SignatureMismatch) {
+  return [
+    `Signature mismatch (${field}). `,
+    `Please ensure you don't call globalCache.get("${key}") from multiple places.\n`,
+    `1-st call ${field}: ${value1}\n`,
+    `2-nd call ${field}: ${value2}`,
+  ].join('');
+}

package/src/server/index.ts

@@ -0,0 +1,81 @@
+/**
+ * Storage Server.
+ * An HTTP server that provides a simple key-value globalCache.
+ * Can be launched locally or on a dedicated environment (standalone).
+ *
+ * This file is exported separately from the main index file, to not be loaded in workers.
+ */
+import http from 'node:http';
+import { AddressInfo } from 'net';
+import express from 'express';
+import { debug } from '../shared/debug';
+import { router as routeGet } from './routes/get';
+import { router as routeSet } from './routes/set';
+import { router as routeGetStale } from './routes/get-stale';
+import { router as routeGetStaleList } from './routes/get-stale-list';
+import { router as routeClearSession } from './routes/clear';
+import { errorHandler } from './error';
+import { getConfig, GlobalCacheServerConfig, setConfig } from './config';
+import { getStorage } from './storage';
+import { startExpressServer } from './utils/express';
+
+export class GlobalCacheServer {
+  private app = express();
+  private server: http.Server | null = null;
+
+  constructor() {
+    this.app.use(express.json());
+    this.app.use('/', routeGet);
+    this.app.use('/', routeSet);
+    this.app.use('/', routeGetStale);
+    this.app.use('/', routeGetStaleList);
+    this.app.use('/', routeClearSession);
+    // todo:
+    // this.app.get('/', (req, res) => {
+    //   res.send('Global Storage Server is running.');
+    // });
+    // Must be after all other middleware and routes
+    this.app.use(errorHandler);
+  }
+
+  get port() {
+    const { port = 0 } = this.server ? (this.server.address() as AddressInfo) : {};
+    return port;
+  }
+
+  get localUrl() {
+    return `http://localhost:${this.port}`;
+  }
+
+  get isRunning() {
+    return Boolean(this.server?.listening);
+  }
+
+  async start(config: GlobalCacheServerConfig) {
+    // todo: if server is already running?
+    debug('Starting server...');
+    setConfig(this.app, config);
+    this.server = await startExpressServer(this.app, config.port);
+    debug(`Server started on port: ${this.port}`);
+  }
+
+  async stop() {
+    if (!this.isRunning) return;
+    debug('Stopping server...');
+    await new Promise<void>((resolve, reject) => {
+      this.server?.close((err) => (err ? reject(err) : resolve()));
+    });
+    this.server = null;
+    debug('Server stopped.');
+  }
+
+  async clearTestRun(runId: string) {
+    if (!this.isRunning) return;
+    const config = getConfig(this.app);
+    const { testRunStorage } = getStorage(config, runId);
+    await testRunStorage.clear();
+  }
+}
+
+/* Export a default instance - convenient for usage */
+export const globalCacheServer = new GlobalCacheServer();

package/src/server/routes/clear.ts

@@ -0,0 +1,15 @@
+import { Express, Router } from 'express';
+import { getConfig } from '../config';
+import { getStorage } from '../storage';
+
+export const router = Router();
+
+router.post('/run/:runId/clear', async (req, res) => {
+  const { runId } = req.params;
+  const config = getConfig(req.app as Express);
+
+  const { testRunStorage } = getStorage(config, runId);
+  await testRunStorage.clear();
+
+  res.end();
+});

package/src/server/routes/get-stale-list.ts

@@ -0,0 +1,27 @@
+import { Express, Router } from 'express';
+import { getConfig } from '../config';
+import { getStorage } from '../storage';
+import { TestRunValueInfo } from '../../shared/value-info';
+
+export const router = Router();
+
+export type GetStaleListParams = {
+  prefix: string;
+};
+
+export type SetStaleListResponse = TestRunValueInfo[];
+
+/**
+ * Returns a list of stale values by prefix.
+ * For stale we return only values used in this test-run.
+ */
+router.get('/run/:runId/get-stale-list', async (req, res) => {
+  const { runId } = req.params;
+  const { prefix } = req.query as GetStaleListParams;
+  const config = getConfig(req.app as Express);
+
+  const { testRunStorage } = getStorage(config, runId);
+  const valueInfoList = await testRunStorage.loadByPrefix(prefix);
+
+  res.json(valueInfoList);
+});

package/src/server/routes/get-stale.ts

@@ -0,0 +1,27 @@
+import { Express, Router } from 'express';
+import { getConfig } from '../config';
+import { getStorage } from '../storage';
+import { TestRunValueInfo } from '../../shared/value-info';
+
+export const router = Router();
+
+export type GetStaleParams = {
+  key: string;
+};
+
+export type SetStaleResponse = TestRunValueInfo | null;
+
+/**
+ * Returns a stale value.
+ * For stale we return only values used in this test-run.
+ */
+router.get('/run/:runId/get-stale', async (req, res) => {
+  const { runId } = req.params;
+  const { key } = req.query as GetStaleParams;
+  const config = getConfig(req.app as Express);
+
+  const { testRunStorage } = getStorage(config, runId);
+  const valueInfo = await testRunStorage.load(key);
+
+  res.json(valueInfo ?? null);
+});

package/src/server/routes/get.ts

@@ -0,0 +1,31 @@
+import { Express, Router } from 'express';
+import { parseTTL } from '../../shared/ttl';
+import { getConfig } from '../config';
+import { Getter, GetterResult } from '../getter';
+import { getStorage } from '../storage';
+
+export const router = Router();
+
+export type GetValueParams = {
+  key: string;
+  sig: string;
+  ttl?: string;
+};
+
+export type GetValueResponse = GetterResult;
+
+/**
+ * Route for geting a value.
+ */
+router.get('/run/:runId/get', async (req, res) => {
+  const { runId } = req.params;
+  const { key, sig, ttl: ttlParam } = req.query as GetValueParams;
+  const config = getConfig(req.app as Express);
+  const ttl = parseTTL(ttlParam);
+
+  const { testRunStorage, persistentStorage } = getStorage(config, runId);
+  const getter = new Getter(testRunStorage, persistentStorage);
+  const data = await getter.get(key, sig, ttl);
+
+  res.json(data);
+});