@renatorodrigues/cacheiro

Core library for the NX remote cache server. Implements the NX 20.8+ custom remote cache specification.

This package provides the server logic and the public API. It is not a runnable application — use @renatorodrigues/cacheiro-runner to run it, or build your own runner on top of the exported API.

Requirements

• Node.js 22+

API

new Cacheiro(store: CacheiroStore, config: CacheiroConfig)

Creates a server instance. Accepts a CacheiroStore implementation and a CacheiroConfig object. Config is not validated at runtime — only TypeScript types are enforced. Validate before constructing using configSchema.

cacheiro.start(): Promise<FastifyInstance>

Builds the Fastify server and returns the Fastify instance. The server is not yet listening — use the returned instance to add custom routes, hooks, or plugins before calling listen().

cacheiro.listen(): Promise<void>

Binds the server to the configured host and port, then prints the startup banner.

cacheiro.stop(): Promise<void>

Drains open connections and shuts down the server gracefully.

import { Cacheiro } from '@renatorodrigues/cacheiro';
import { FileSystemStore } from '@renatorodrigues/cacheiro-store-fs';

const store = new FileSystemStore({
  cacheDirectory: './cache',
  ttlDays: 7,
  sweepIntervalHours: 24,
});

const cacheiro = new Cacheiro(store, {
  server: { port: 3000, host: '127.0.0.1', bodyLimitMb: 100, banner: true, infobox: true },
  auth: { token: 'my-secret-token' },
});

const server = await cacheiro.start();

// add custom routes, hooks, or plugins here before listen()

await cacheiro.listen();

CacheiroStore

Interface that all store implementations must satisfy. Import it to build a custom store:

import type { CacheiroStore } from '@renatorodrigues/cacheiro';

CacheiroConfig

TypeScript interface describing the server configuration shape. Import it to type your own config loader:

| Field | Type | Required | Default | Description | | --------------------- | --------- | -------- | ------- | ---------------------------------------------------------------------- | | server.port | number | Yes | — | Port to listen on. | | server.host | string | Yes | — | Host to bind to (e.g. "127.0.0.1" or "0.0.0.0"). | | server.bodyLimitMb | number | No | 100 | Maximum request body size in megabytes. | | server.banner | boolean | No | true | Show the large ASCII art banner on startup. Compact header if false. | | server.infobox | boolean | No | true | Show the info box (version, URL, store details) on startup. | | server.tls.certFile | string | No | — | Path to PEM certificate file. Enables HTTPS when set (with keyFile). | | server.tls.keyFile | string | No | — | Path to PEM private key file. | | server.tls.caFile | string | No | — | Path to CA certificate file (optional). | | auth.token | string | Yes | — | Bearer token required on all requests. Auth disabled if empty. |

import type { CacheiroConfig } from '@renatorodrigues/cacheiro';

configSchema

JSON Schema (draft-07) for CacheiroConfig. Exported for runners and custom integrations to validate config before constructing Cacheiro:

import { configSchema } from '@renatorodrigues/cacheiro';
import { Ajv } from 'ajv';

const ajv = new Ajv({ allErrors: true });
const validate = ajv.compile(configSchema);

HTTP API

Defined by swagger.json (OpenAPI 3.0).

| Method | Path | Auth required | Description | | ------ | ----------------- | ------------- | ------------------------------- | | PUT | /v1/cache/:hash | Yes | Upload a task artifact | | GET | /v1/cache/:hash | Yes | Download a task artifact | | GET | /health | No | Health check — returns 200 OK |

/v1/cache/* endpoints require an Authorization: Bearer <token> header when auth.token is set.

Stores

Store packages implement the CacheiroStore interface and are independent of this package. Instantiate the store of your choice and pass it to the Cacheiro constructor.

See @renatorodrigues/cacheiro-types for the full list of available stores and instructions on implementing a custom store.

Development

npm run watch        # tsc --watch (hot rebuild)
npm run build        # compile TypeScript
npm test             # run tests
npm run test:watch   # watch mode
npm run lint         # oxlint
npm run fmt          # oxfmt