### TypeScript SDK - `createClient`

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Demonstrates how to use the `createClient` function from the provided TypeScript SDK to interact with the Management API. It shows examples of listing, matching, and deleting cache entries.

```APIDOC
## TypeScript SDK — `createClient`

### Description
The bundled SDK (`sdk/index.ts`) creates a fully-typed oRPC client for the Management API, inferring all input/output types directly from the server router definition.

### Usage
```typescript
import { createClient } from './sdk/index'

// Create a typed client pointing at the running server
const client = createClient('http://localhost:3000', 'my-secret-key')

async function main() {
  // List cache entries — fully typed response
  const { total, items } = await client.cacheEntries.findMany({
    page: 1,
    itemsPerPage: 10,
    repoId: '123456789',
  })
  console.log(`Found ${total} entries:`, items.map((e) => e.key))

  // Match with restore keys (same logic as GetCacheEntryDownloadURL)
  const result = await client.cacheEntries.match({
    primaryKey: 'npm-linux-abc123',
    restoreKeys: ['npm-linux-', 'npm-'],
    scopes: ['refs/heads/main'],
    repoId: '123456789',
    version: 'v1',
  })
  if (result) {
    console.log(`Matched via "${result.type}":`, result.match.key)
  }

  // Delete a stale entry
  await client.cacheEntries.delete({ id: items[0]!.id })

  // Bulk-delete entries older than a specific key pattern
  await client.cacheEntries.deleteMany({ key: 'npm-linux-abc123' })
}

main().catch(console.error)
```

### Methods
- **`createClient(baseUrl: string, apiKey: string)`**: Initializes the client.
- **`client.cacheEntries.findMany(params: { page: number, itemsPerPage: number, key?: string, version?: string, scope?: string, repoId?: string })`**: Lists cache entries with pagination and filtering.
- **`client.cacheEntries.match(params: { primaryKey: string, restoreKeys: string[], scopes: string[], repoId?: string, version?: string })`**: Matches cache entries based on provided keys and criteria.
- **`client.cacheEntries.delete(params: { id: string })`**: Deletes a single cache entry by ID.
- **`client.cacheEntries.deleteMany(params: { key?: string, version?: string, scope?: string, repoId?: string })`**: Deletes multiple cache entries based on filter criteria.
```

--------------------------------

### Deploy GitHub Actions Cache Server with Helm

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Deploy the server to Kubernetes using the bundled Helm chart. This example configures S3 storage and PostgreSQL, and requires a secret containing AWS credentials and database connection URL.

```bash
helm install gha-cache ./install/kubernetes/github-actions-cache-server \
  --namespace ci --create-namespace \
  --set config.apiBaseUrl=https://cache.example.com \
  --set config.storage.driver=s3 \
  --set config.storage.s3.bucket=my-cache-bucket \
  --set config.storage.s3.region=us-east-1 \
  --set config.db.driver=postgres \
  --set config.managementApiKey=my-secret-key \
  --set existingSecret=gha-cache-secrets   # Secret with AWS_SECRET_ACCESS_KEY, DB_POSTGRES_URL
```

--------------------------------

### Deploy GitHub Actions Cache Server with Helm

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Use Helm to upgrade or install the GitHub Actions Cache Server. This command deploys the server using a production values file for configuration.

```bash
helm upgrade gha-cache ./install/kubernetes/github-actions-cache-server \
  --namespace ci -f values-production.yaml
```

--------------------------------

### Management API - Get Cache Entry

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Retrieves a single cache entry by its UUID. Requires the X-Api-Key header. Returns 404 if the entry is not found.

```bash
BASE="http://localhost:3000/management-api"
KEY="my-secret-key"
ID="550e8400-e29b-41d4-a716-446655440000"

curl -s "$BASE/cache-entries/$ID" -H "X-Api-Key: $KEY" | jq .
# {
#   "id": "550e8400-e29b-41d4-a716-446655440000",
#   "key": "npm-linux-abc123",
#   "version": "v1",
#   "scope": "refs/heads/main",
#   "repoId": "123456789",
#   "updatedAt": 1700000000000,
#   "locationId": "660e8400-e29b-41d4-a716-446655440001"
# }

# Not found
curl -s -o /dev/null -w "%{http_code}" \
  "$BASE/cache-entries/00000000-0000-0000-0000-000000000000" -H "X-Api-Key: $KEY"
# 404
```

--------------------------------

### Docker Compose Configuration for Cache Server

Source: https://github.com/falcondev-oss/github-actions-cache-server/blob/dev/README.md

This configuration sets up the GitHub Actions Cache Server as a Docker service. It specifies the image, port mapping, environment variables for storage and database drivers, and volume mounts for persistent data. Ensure the API_BASE_URL matches your local setup.

```yaml
services:
  cache-server:
    image: ghcr.io/falcondev-oss/github-actions-cache-server
    ports:
      - '3000:3000'
    environment:
      API_BASE_URL: http://localhost:3000
      STORAGE_DRIVER: filesystem
      STORAGE_FILESYSTEM_PATH: /data/cache
      DB_DRIVER: sqlite
      DB_SQLITE_PATH: /data/cache-server.db
    volumes:
      - cache-data:/data

volumes:
  cache-data:
```

--------------------------------

### Get Cache Entry

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Retrieves a single cache entry by its UUID. Returns 404 when not found.

```APIDOC
## GET /management-api/cache-entries/:id

### Description
Retrieves a single cache entry by its UUID. Returns 404 when not found.

### Method
GET

### Endpoint
/management-api/cache-entries/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The UUID of the cache entry to retrieve.

### Request Example
```bash
BASE="http://localhost:3000/management-api"
KEY="my-secret-key"
ID="550e8400-e29b-41d4-a716-446655440000"

curl -s "$BASE/cache-entries/$ID" -H "X-Api-Key: $KEY" | jq .
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier of the cache entry.
- **key** (string) - The cache key.
- **version** (string) - The cache version.
- **scope** (string) - The scope of the cache entry (e.g., branch or tag).
- **repoId** (string) - The repository ID.
- **updatedAt** (integer) - Timestamp of the last update.
- **locationId** (string) - The location identifier of the cache entry.

#### Error Response (404)
- Returned when the cache entry with the specified ID is not found.

### Response Example
```json
{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "key": "npm-linux-abc123",
  "version": "v1",
  "scope": "refs/heads/main",
  "repoId": "123456789",
  "updatedAt": 1700000000000,
  "locationId": "660e8400-e29b-41d4-a716-446655440001"
}
```

```bash
# Not found
curl -s -o /dev/null -w "%{http_code}" \
  "$BASE/cache-entries/00000000-0000-0000-0000-000000000000" -H "X-Api-Key: $KEY"
# 404
```
```

--------------------------------

### Get Cache Entry Download URL with Twirp API

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Use the GetCacheEntryDownloadURL Twirp API to resolve the best-matching cache entry. Returns a download URL, which may be a direct storage provider URL if ENABLE_DIRECT_DOWNLOADS is true.

```bash
curl -s -X POST http://localhost:3000/twirp/github.actions.results.api.v1.CacheService/GetCacheEntryDownloadURL \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <github-actions-jwt>" \
  -d '{
    "key": "npm-linux-abc123",
    "restore_keys": ["npm-linux-", "npm-"],
    "version": "v1"
  }' | jq .
```

```json
# Match found
{
  "ok": true,
  "signed_download_url": "http://localhost:3000/download/550e8400-e29b-41d4-a716-446655440000",
  "matched_key": "npm-linux-abc123"
}
```

```json
# No match
{ "ok": false }
```

--------------------------------

### Get Storage Location Metadata via Management API

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Retrieve detailed metadata for a storage location using its UUID. This includes information such as folder name, part count, and timestamps for merges and downloads.

```bash
BASE="http://localhost:3000/management-api"
KEY="my-secret-key"
LOC_ID="660e8400-e29b-41d4-a716-446655440001"

curl -s "$BASE/storage-locations/$LOC_ID" -H "X-Api-Key: $KEY" | jq .
```

--------------------------------

### Get Storage Location

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Retrieves detailed metadata for a specific storage location using its UUID. This includes information such as the associated folder name, part count, merge timestamps, and the last download time.

```APIDOC
## GET /management-api/storage-locations/:id

### Description
Retrieves the metadata for a storage location by UUID, including its folder name, part count, merge timestamps, and last download time.

### Method
GET

### Endpoint
/management-api/storage-locations/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The UUID of the storage location to retrieve.

### Request Example
```bash
BASE="http://localhost:3000/management-api"
KEY="my-secret-key"
LOC_ID="660e8400-e29b-41d4-a716-446655440001"

curl -s "$BASE/storage-locations/$LOC_ID" -H "X-Api-Key: $KEY" | jq .
```

### Response
#### Success Response (200)
- **id** (string) - The UUID of the storage location.
- **folderName** (string) - The name of the associated folder in the storage backend.
- **partCount** (integer) - The number of parts in the storage location.
- **mergeStartedAt** (integer) - Timestamp (in milliseconds) when the merge operation started.
- **mergedAt** (integer) - Timestamp (in milliseconds) when the merge operation completed.
- **partsDeletedAt** (integer) - Timestamp (in milliseconds) when the parts were deleted.
- **lastDownloadedAt** (integer) - Timestamp (in milliseconds) of the last download.

#### Response Example
```json
{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "folderName": "1234567890",
  "partCount": 3,
  "mergeStartedAt": 1700000100000,
  "mergedAt": 1700000200000,
  "partsDeletedAt": 1700000300000,
  "lastDownloadedAt": 1700000400000
}
```
```

--------------------------------

### FinalizeCacheEntryUpload

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Finalizes a completed multipart upload. Validates that all started parts finished uploading and that the actual file count in storage matches the expected part count. On success, atomically inserts (or updates) the cache entry record and cleans up the pending upload record. Returns the new entry ID.

```APIDOC
## POST /twirp/github.actions.results.api.v1.CacheService/FinalizeCacheEntryUpload

### Description
Finalizes a completed multipart upload. Validates that all started parts finished uploading and that the actual file count in storage matches the expected part count. On success, atomically inserts (or updates) the cache entry record and cleans up the pending upload record. Returns the new entry ID.

### Method
POST

### Endpoint
/twirp/github.actions.results.api.v1.CacheService/FinalizeCacheEntryUpload

### Parameters
#### Request Body
- **key** (string) - Required - The key of the cache entry.
- **version** (string) - Required - The version of the cache entry.

### Request Example
```json
{
  "key": "npm-linux-abc123",
  "version": "v1"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **entry_id** (string) - The ID of the finalized cache entry.

#### Response Example
```json
{
  "ok": true,
  "entry_id": "1234567890"
}
```

#### Error Response (404)
- Description: Upload not found (e.g. never created, or already finalized).

```

--------------------------------

### Management API - Authentication and List Cache Entries

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Demonstrates Management API authentication using the X-Api-Key header and lists cache entries with optional filtering and pagination. Requires MANAGEMENT_API_KEY to be set.

```bash
# All management calls require X-Api-Key
BASE="http://localhost:3000/management-api"
KEY="my-secret-key"

# Missing key → 401 Unauthorized
curl -s -o /dev/null -w "%{http_code}" "$BASE/cache-entries"
# 401

# List all entries (page 1, 20 per page)
curl -s "$BASE/cache-entries" -H "X-Api-Key: $KEY" | jq . 
# { 
#   "total": 42, 
#   "items": [ 
#     { 
#       "id": "550e8400-e29b-41d4-a716-446655440000", 
#       "key": "npm-linux-abc123", 
#       "version": "v1", 
#       "scope": "refs/heads/main", 
#       "repoId": "123456789", 
#       "updatedAt": 1700000000000, 
#       "locationId": "660e8400-e29b-41d4-a716-446655440001" 
#     } 
#   ] 
# }

# Filter by key prefix and paginate
curl -s "$BASE/cache-entries?key=npm-linux-abc123&page=1&itemsPerPage=5" \
  -H "X-Api-Key: $KEY" | jq '.total, (.items | length)'

# Filter by scope and repoId
curl -s "$BASE/cache-entries?scope=refs%2Fheads%2Fmain&repoId=123456789" \
  -H "X-Api-Key: $KEY" | jq '[.items[].key]'
```

--------------------------------

### Initialize and Use TypeScript SDK Client

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Create a typed oRPC client for the Management API using `createClient`. This SDK infers types directly from the server router definition. Use the client to perform operations like listing, matching, and deleting cache entries.

```typescript
import { createClient } from './sdk/index'

// Create a typed client pointing at the running server
const client = createClient('http://localhost:3000', 'my-secret-key')

async function main() {
  // List cache entries — fully typed response
  const { total, items } = await client.cacheEntries.findMany({
    page: 1,
    itemsPerPage: 10,
    repoId: '123456789',
  })
  console.log(`Found ${total} entries:`, items.map((e) => e.key))

  // Match with restore keys (same logic as GetCacheEntryDownloadURL)
  const result = await client.cacheEntries.match({
    primaryKey: 'npm-linux-abc123',
    restoreKeys: ['npm-linux-', 'npm-'],
    scopes: ['refs/heads/main'],
    repoId: '123456789',
    version: 'v1',
  })
  if (result) {
    console.log(`Matched via "${result.type}":`, result.match.key)
  }

  // Delete a stale entry
  await client.cacheEntries.delete({ id: items[0]!.id })

  // Bulk-delete entries older than a specific key pattern
  await client.cacheEntries.deleteMany({ key: 'npm-linux-abc123' })
}

main().catch(console.error)
```

--------------------------------

### GetCacheEntryDownloadURL

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Resolves the best-matching cache entry for a given key, optional restore keys, and version. Returns a download URL. The server first tries exact primary key match, then prefix-based primary match, then exact/prefix restore key matches, in scope priority order. When ENABLE_DIRECT_DOWNLOADS=true and the entry has been merged, returns a pre-signed storage provider URL (valid 10 min) instead of proxying through the server.

```APIDOC
## POST /twirp/github.actions.results.api.v1.CacheService/GetCacheEntryDownloadURL

### Description
Resolves the best-matching cache entry for a given key, optional restore keys, and version. Returns a download URL. The server first tries exact primary key match, then prefix-based primary match, then exact/prefix restore key matches, in scope priority order. When `ENABLE_DIRECT_DOWNLOADS=true` and the entry has been merged, returns a pre-signed storage provider URL (valid 10 min) instead of proxying through the server.

### Method
POST

### Endpoint
/twirp/github.actions.results.api.v1.CacheService/GetCacheEntryDownloadURL

### Parameters
#### Request Body
- **key** (string) - Required - The primary key for the cache entry.
- **restore_keys** (array of strings) - Optional - A list of keys to try if the primary key is not found.
- **version** (string) - Required - The version of the cache entry.

### Request Example
```json
{
  "key": "npm-linux-abc123",
  "restore_keys": ["npm-linux-", "npm-"],
  "version": "v1"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if a match was found.
- **signed_download_url** (string) - The signed URL for downloading the cache entry.
- **matched_key** (string) - The key that matched the cache entry.

#### Response Example
```json
{
  "ok": true,
  "signed_download_url": "http://localhost:3000/download/550e8400-e29b-41d4-a716-446655440000",
  "matched_key": "npm-linux-abc123"
}
```

#### Error Response
- **ok** (boolean) - Indicates if a match was found.

#### Response Example
```json
{
  "ok": false
}
```
```

--------------------------------

### Management API - Match Cache Entry

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Simulates the server's cache resolution logic for a download request. Requires the X-Api-Key header. Returns the matched entry and its type, or null if no match.

```bash
BASE="http://localhost:3000/management-api"
KEY="my-secret-key"

curl -s "$BASE/cache-entries/match" \
  -H "X-Api-Key: $KEY" \
  -G \
  --data-urlencode "primaryKey=npm-linux-abc123" \
  --data-urlencode "restoreKeys=npm-linux-" \
  --data-urlencode "restoreKeys=npm-" \
  --data-urlencode "scopes=refs/heads/main" \
  --data-urlencode "scopes=refs/heads/master" \
  --data-urlencode "repoId=123456789" \
  --data-urlencode "version=v1" | jq .

# Exact match on primary key
# {
#   "match": { "id": "550e8400...", "key": "npm-linux-abc123", ... },
#   "type": "exact-primary"
# }

# Prefix match on a restore key
# {
#   "match": { "id": "660e8400...", "key": "npm-linux-older", ... },
#   "type": "prefixed-restore"
# }

# No match at all
# null
```

--------------------------------

### Docker Compose Deployment for Cache Server

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Deploy the cache server with filesystem storage and SQLite using Docker Compose. Ensure the API_BASE_URL is reachable by your runners. The MANAGEMENT_API_KEY enables the Management API.

```yaml
# docker-compose.yml
services:
  cache-server:
    image: ghcr.io/falcondev-oss/github-actions-cache-server:9.4.7
    ports:
      - '3000:3000'
    environment:
      API_BASE_URL: http://localhost:3000        # Must be reachable by your runners
      STORAGE_DRIVER: filesystem
      STORAGE_FILESYSTEM_PATH: /data/cache
      DB_DRIVER: sqlite
      DB_SQLITE_PATH: /data/cache-server.db
      MANAGEMENT_API_KEY: my-secret-key          # Enables the Management API
      CACHE_CLEANUP_OLDER_THAN_DAYS: 90          # Delete entries not downloaded in 90 days
    volumes:
      - cache-data:/data

volumes:
  cache-data:
```

```bash
docker compose up -d
# Verify the server is running
curl http://localhost:3000/health
# Output: healthy
```

--------------------------------

### Cache Server Environment Variables Configuration

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Configure the cache server using environment variables for various storage and database backends. Required variables include API_BASE_URL. Optional settings like MANAGEMENT_API_KEY and CACHE_CLEANUP_OLDER_THAN_DAYS can be set for enhanced functionality.

```bash
# ── Required ─────────────────────────────────────────────────────────────
API_BASE_URL=https://cache.example.com   # Public URL reachable by runners

# ── Storage: filesystem (default) ────────────────────────────────────────
STORAGE_DRIVER=filesystem
STORAGE_FILESYSTEM_PATH=.data/storage/filesystem

# ── Storage: S3 / MinIO ───────────────────────────────────────────────────
STORAGE_DRIVER=s3
STORAGE_S3_BUCKET=my-cache-bucket
AWS_REGION=us-east-1
AWS_ENDPOINT_URL=http://minio:9000       # Omit for AWS; set for MinIO
AWS_ACCESS_KEY_ID=access_key
AWS_SECRET_ACCESS_KEY=secret_key

# ── Storage: Google Cloud Storage ────────────────────────────────────────
STORAGE_DRIVER=gcs
STORAGE_GCS_BUCKET=my-gcs-bucket
STORAGE_GCS_SERVICE_ACCOUNT_KEY=/path/to/service-account.json
STORAGE_GCS_ENDPOINT=https://storage.googleapis.com   # Optional custom endpoint

# ── Database: SQLite (default) ────────────────────────────────────────────
DB_DRIVER=sqlite
DB_SQLITE_PATH=.data/sqlite.db

# ── Database: PostgreSQL ──────────────────────────────────────────────────
DB_DRIVER=postgres
DB_POSTGRES_URL=postgresql://user:pass@localhost:5432/cache   # OR individual fields:
DB_POSTGRES_HOST=localhost
DB_POSTGRES_PORT=5432
DB_POSTGRES_DATABASE=cache
DB_POSTGRES_USER=user
DB_POSTGRES_PASSWORD=pass

# ── Database: MySQL ───────────────────────────────────────────────────────
DB_DRIVER=mysql
DB_MYSQL_HOST=localhost
DB_MYSQL_PORT=3306
DB_MYSQL_DATABASE=cache
DB_MYSQL_USER=user
DB_MYSQL_PASSWORD=pass

# ── Optional settings ─────────────────────────────────────────────────────
MANAGEMENT_API_KEY=my-secret-key        # Enables the Management API (disabled if unset)
CACHE_CLEANUP_OLDER_THAN_DAYS=90        # Default: 90; 0 disables age-based cleanup
DISABLE_CLEANUP_JOBS=false              # Disable all scheduled cleanup tasks
ENABLE_DIRECT_DOWNLOADS=false           # Send signed storage URLs instead of proxying
DEBUG=false                             # Verbose request/response logging
SKIP_TOKEN_VALIDATION=false             # DANGER: disable JWT validation (dev only)
```

--------------------------------

### Management API - View OpenAPI Spec

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Retrieves the OpenAPI specification for the Management API. Requires the X-Api-Key header.

```bash
# View the OpenAPI spec
curl -s http://localhost:3000/management-api/_docs/spec.json | jq .info
```

--------------------------------

### Configure Self-Hosted Cache Server in GitHub Actions Workflow

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Set environment variables in your GitHub Actions workflow to redirect the actions/cache to a self-hosted cache server. Requires a runner with the 'self-hosted' label.

```yaml
jobs:
  build:
    runs-on: self-hosted
    env:
      # Redirect the cache action to the self-hosted server
      ACTIONS_CACHE_URL: http://cache.example.com/
      ACTIONS_RUNTIME_TOKEN: ${{ secrets.GITHUB_TOKEN }}
    steps:
      - uses: actions/checkout@v4

      - name: Cache node_modules
        uses: actions/cache@v4
        with:
          path: ~/.npm
          key: npm-${{ runner.os }}-${{ hashFiles('**/package-lock.json') }}
          restore-keys: |
            npm-${{ runner.os }}-

      - run: npm ci
```

--------------------------------

### CreateCacheEntry

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Creates a new upload session for a cache entry. The action sends this request before uploading cache data. The server returns a signed upload URL pointing to the multipart upload endpoint. Requires a valid GitHub Actions JWT in the Authorization: Bearer header containing repository scope claims.

```APIDOC
## POST /twirp/github.actions.results.api.v1.CacheService/CreateCacheEntry

### Description
Creates a new upload session for a cache entry. The action sends this request before uploading cache data. The server returns a signed upload URL pointing to the multipart upload endpoint. Requires a valid GitHub Actions JWT in the `Authorization: Bearer` header containing repository scope claims.

### Method
POST

### Endpoint
/twirp/github.actions.results.api.v1.CacheService/CreateCacheEntry

### Parameters
#### Request Body
- **key** (string) - Required - The key for the cache entry.
- **version** (string) - Required - The version of the cache entry.

### Request Example
```json
{
  "key": "npm-linux-abc123",
  "version": "v1"
}
```

### Response
#### Success Response (200)
- **ok** (boolean) - Indicates if the operation was successful.
- **signed_upload_url** (string) - The signed URL for uploading cache data.

#### Response Example
```json
{
  "ok": true,
  "signed_upload_url": "http://localhost:3000/devstoreaccount1/upload/1234567890"
}
```

#### Error Response
- **ok** (boolean) - Indicates if the operation was successful.

#### Response Example
```json
{
  "ok": false
}
```
```

--------------------------------

### Create Cache Entry with Twirp API

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Use the CreateCacheEntry Twirp API to initiate a new upload session for a cache entry. This is typically called by actions/cache before uploading data. Requires a GitHub Actions JWT in the Authorization header.

```bash
# Typically called by actions/cache, but can be tested directly with SKIP_TOKEN_VALIDATION=true
curl -s -X POST http://localhost:3000/twirp/github.actions.results.api.v1.CacheService/CreateCacheEntry \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <github-actions-jwt>" \
  -d '{"key": "npm-linux-abc123", "version": "v1"}' | jq .
```

```json
# Success response — upload to the returned URL using the Upload Part endpoint
{
  "ok": true,
  "signed_upload_url": "http://localhost:3000/devstoreaccount1/upload/1234567890"
}
```

```json
# When an upload for the same key+version+scope already exists
{ "ok": false }
```

--------------------------------

### Match Cache Entry

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Simulates the cache resolution logic to find a matching cache entry based on provided keys, scopes, and repository ID. Returns the matched entry and its match type, or null if no match is found.

```APIDOC
## GET /management-api/cache-entries/match

### Description
Simulates the exact cache resolution logic the server uses during a `GetCacheEntryDownloadURL` request. Returns the matched entry and a match type string (`exact-primary`, `prefixed-primary`, `exact-restore`, `prefixed-restore`) or `null` when nothing matches.

### Method
GET

### Endpoint
/management-api/cache-entries/match

### Parameters
#### Query Parameters
- **primaryKey** (string) - Optional - The primary cache key to match against.
- **restoreKeys** (string array) - Optional - An array of restore keys to match against.
- **scopes** (string array) - Optional - An array of scopes (e.g., branch or tag) to filter by.
- **repoId** (string) - Optional - The repository ID to filter by.
- **version** (string) - Optional - The cache version to filter by.

### Request Example
```bash
BASE="http://localhost:3000/management-api"
KEY="my-secret-key"

curl -s "$BASE/cache-entries/match" \
  -H "X-Api-Key: $KEY" \
  -G \
  --data-urlencode "primaryKey=npm-linux-abc123" \
  --data-urlencode "restoreKeys=npm-linux-" \
  --data-urlencode "restoreKeys=npm-" \
  --data-urlencode "scopes=refs/heads/main" \
  --data-urlencode "scopes=refs/heads/master" \
  --data-urlencode "repoId=123456789" \
  --data-urlencode "version=v1" | jq .
```

### Response
#### Success Response (200)
- **match** (object | null) - The matched cache entry object, or null if no match is found. If an object, it contains fields like `id`, `key`, `version`, `scope`, `repoId`, `updatedAt`, and `locationId`.
- **type** (string) - The type of match found (e.g., `exact-primary`, `prefixed-primary`, `exact-restore`, `prefixed-restore`).

### Response Example
```json
# Exact match on primary key
{
  "match": { "id": "550e8400...", "key": "npm-linux-abc123", ... },
  "type": "exact-primary"
}

# Prefix match on a restore key
{
  "match": { "id": "660e8400...", "key": "npm-linux-older", ... },
  "type": "prefixed-restore"
}

# No match at all
null
```
```

--------------------------------

### List Cache Entries

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Returns a paginated list of cache entries with optional filters for key, version, scope, and repository ID. Useful for auditing cached data.

```APIDOC
## GET /management-api/cache-entries

### Description
Returns a paginated list of cache entries with optional filters for key, version, scope, and repository ID. Useful for auditing cached data and building cache management dashboards.

### Method
GET

### Endpoint
/management-api/cache-entries

### Parameters
#### Query Parameters
- **key** (string) - Optional - Filters entries by cache key.
- **version** (string) - Optional - Filters entries by cache version.
- **scope** (string) - Optional - Filters entries by scope (e.g., branch or tag).
- **repoId** (string) - Optional - Filters entries by repository ID.
- **page** (integer) - Optional - The page number for pagination (default is 1).
- **itemsPerPage** (integer) - Optional - The number of items per page for pagination (default is 20).

### Request Example
```bash
BASE="http://localhost:3000/management-api"
KEY="my-secret-key"

# List all entries (page 1, 20 per page)
curl -s "$BASE/cache-entries" -H "X-Api-Key: $KEY" | jq .

# Filter by key prefix and paginate
curl -s "$BASE/cache-entries?key=npm-linux-abc123&page=1&itemsPerPage=5" \
  -H "X-Api-Key: $KEY" | jq '.total, (.items | length)'

# Filter by scope and repoId
curl -s "$BASE/cache-entries?scope=refs%2Fheads%2Fmain&repoId=123456789" \
  -H "X-Api-Key: $KEY" | jq '[.items[].key]'
```

### Response
#### Success Response (200)
- **total** (integer) - The total number of cache entries matching the filters.
- **items** (array) - An array of cache entry objects.
  - **id** (string) - The unique identifier of the cache entry.
  - **key** (string) - The cache key.
  - **version** (string) - The cache version.
  - **scope** (string) - The scope of the cache entry (e.g., branch or tag).
  - **repoId** (string) - The repository ID.
  - **updatedAt** (integer) - Timestamp of the last update.
  - **locationId** (string) - The location identifier of the cache entry.

### Response Example
```json
{
  "total": 42,
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "key": "npm-linux-abc123",
      "version": "v1",
      "scope": "refs/heads/main",
      "repoId": "123456789",
      "updatedAt": 1700000000000,
      "locationId": "660e8400-e29b-41d4-a716-446655440001"
    }
  ]
}
```
```

--------------------------------

### Download Cache Entry

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Streams the binary contents of a cache entry by its UUID. The server handles merged and unmerged parts automatically. Stale entries return 404.

```bash
# Download a cache entry to a local file
curl -s http://localhost:3000/download/550e8400-e29b-41d4-a716-446655440000 \
  -o restored-cache.tar.gz
# The response body is the raw binary cache archive

# Check for a stale/missing entry
curl -s -o /dev/null -w "%{http_code}" \
  http://localhost:3000/download/00000000-0000-0000-0000-000000000000
# 404
```

--------------------------------

### Upload Part

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Streams a single chunk of cache data to storage. Compatible with the Azure Blob Storage block upload protocol used by `actions/cache` and `docker buildx`. The `blockid` query parameter is decoded to determine the chunk index (supports both 48-byte standard and 64-byte docker buildx formats). When `comp=blocklist` is passed, the request is treated as a finalization signal and returns 201 with no body.

```APIDOC
## PUT /devstoreaccount1/upload/:uploadId

### Description
Streams a single chunk of cache data to storage. Compatible with the Azure Blob Storage block upload protocol used by `actions/cache` and `docker buildx`. The `blockid` query parameter is decoded to determine the chunk index (supports both 48-byte standard and 64-byte docker buildx formats). When `comp=blocklist` is passed, the request is treated as a finalization signal and returns 201 with no body.

### Method
PUT

### Endpoint
/devstoreaccount1/upload/:uploadId

### Parameters
#### Path Parameters
- **uploadId** (string) - Required - The ID of the upload session.

#### Query Parameters
- **blockid** (string) - Optional - Base64 encoded block ID for the chunk.
- **comp** (string) - Optional - Set to `blocklist` to finalize the upload.

#### Request Body
- **(binary)** - Required - The cache data chunk.

### Request Example
```bash
# Upload chunk 0 (small cache file, no blockid needed)
curl -s -X PUT "http://localhost:3000/devstoreaccount1/upload/1234567890" \
  --data-binary @/tmp/cache.tar.gz \
  -H "Content-Type: application/octet-stream" \
  -w "\nHTTP %{http_code}\n"

# Upload chunk 0 using blockid (base64 of "<uuid>0")
BLOCK_ID=$(printf '%s%04d' "$(uuidgen)" 0 | base64)
curl -s -X PUT "http://localhost:3000/devstoreaccount1/upload/1234567890?blockid=${BLOCK_ID}" \
  --data-binary @/tmp/part0.bin \
  -w "\nHTTP %{http_code}\n"

# Finalize block list
curl -s -X PUT "http://localhost:3000/devstoreaccount1/upload/1234567890?comp=blocklist" \
  -w "\nHTTP %{http_code}\n"
```

### Response
#### Success Response (201)
- **(no body)** - Indicates successful upload or finalization.

```

--------------------------------

### Download Cache Entry

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Streams the binary contents of a cache entry by its UUID. The server handles merging parts in the background for faster future downloads. Returns 404 for stale entries.

```APIDOC
## GET /download/:cacheEntryId

### Description
Streams the binary contents of a cache entry by its UUID. The server automatically handles two states: if parts have already been merged into a single object, the merged file is streamed directly; otherwise, parts are streamed sequentially while simultaneously being merged into a single merged object in the background for faster future downloads. Stale entries (where storage objects are missing) return 404.

### Method
GET

### Endpoint
/download/:cacheEntryId

### Parameters
#### Path Parameters
- **cacheEntryId** (string) - Required - The UUID of the cache entry to download.

### Request Example
```bash
# Download a cache entry to a local file
curl -s http://localhost:3000/download/550e8400-e29b-41d4-a716-446655440000 \
  -o restored-cache.tar.gz
```

### Response
#### Success Response (200)
- The response body is the raw binary cache archive.

#### Error Response (404)
- Returned when the cache entry is stale or missing.

### Response Example
```bash
# Check for a stale/missing entry
curl -s -o /dev/null -w "%{http_code}" \
  http://localhost:3000/download/00000000-0000-0000-0000-000000000000
# 404
```
```

--------------------------------

### Health Check

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Returns a plain-text 'healthy' response with HTTP 200. Used for liveness/readiness probes and load balancer checks. Can be used to wait for server startup.

```bash
curl -s http://localhost:3000/health
# healthy

# Use in a shell script to wait for startup
until curl -sf http://localhost:3000/health; do sleep 1; done
echo "Cache server is ready"
```

--------------------------------

### Bulk Delete Cache Entries via Management API

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

This endpoint allows for bulk deletion of cache entries based on filters like key, version, scope, and repoId. If no filters are provided, all entries are deleted. Storage cleanup is triggered asynchronously.

```bash
BASE="http://localhost:3000/management-api"
KEY="my-secret-key"

# Delete all entries for a specific key
curl -s -X DELETE "$BASE/cache-entries?key=npm-linux-abc123" \
  -H "X-Api-Key: $KEY" -w "\nHTTP %{http_code}\n"
# HTTP 200

# Delete all entries for a specific repository
curl -s -X DELETE "$BASE/cache-entries?repoId=123456789" \
  -H "X-Api-Key: $KEY" -w "\nHTTP %{http_code}\n"
# HTTP 200

# Delete everything (no filters)
curl -s -X DELETE "$BASE/cache-entries" \
  -H "X-Api-Key: $KEY" -w "\nHTTP %{http_code}\n"
# HTTP 200
```

--------------------------------

### Upload Cache Data Part

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Stream a chunk of cache data to storage using the Azure Blob Storage block upload protocol. The `blockid` parameter indicates the chunk index. Use `comp=blocklist` to finalize.

```bash
# Upload chunk 0 (small cache file, no blockid needed)
curl -s -X PUT "http://localhost:3000/devstoreaccount1/upload/1234567890" \
  --data-binary @/tmp/cache.tar.gz \
  -H "Content-Type: application/octet-stream" \
  -w "\nHTTP %{http_code}\n"
# HTTP 201
```

```bash
# Upload chunk 0 using blockid (base64 of "<uuid>0")
BLOCK_ID=$(printf '%s%04d' "$(uuidgen)" 0 | base64)
curl -s -X PUT "http://localhost:3000/devstoreaccount1/upload/1234567890?blockid=${BLOCK_ID}" \
  --data-binary @/tmp/part0.bin \
  -w "\nHTTP %{http_code}\n"
# HTTP 201
```

```bash
# Finalize block list
curl -s -X PUT "http://localhost:3000/devstoreaccount1/upload/1234567890?comp=blocklist" \
  -w "\nHTTP %{http_code}\n"
# HTTP 201
```

--------------------------------

### Health Check

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Returns a plain-text 'healthy' response with HTTP 200. Used for liveness/readiness probes and load balancer health checks.

```APIDOC
## GET /health

### Description
Returns a plain-text `healthy` response with HTTP 200. Used by Kubernetes liveness/readiness probes and load balancer health checks.

### Method
GET

### Endpoint
/health

### Response
#### Success Response (200)
- Returns the string `healthy`.

### Request Example
```bash
curl -s http://localhost:3000/health
# healthy

# Use in a shell script to wait for startup
until curl -sf http://localhost:3000/health; do sleep 1; done
echo "Cache server is ready"
```
```

--------------------------------

### Configure Scheduled Cleanup Tasks in Nitro

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Defines the cron schedule for various cleanup tasks within the Nitro configuration. Tasks include cleaning up uploads, merges, parts, cache entries, and storage locations.

```typescript
scheduledTasks: {
  '*/5 * * * *': ['cleanup:uploads'],
  '0 * * * *':   ['cleanup:parts', 'cleanup:merges'],
  '0 0 * * *':   ['cleanup:cache-entries', 'cleanup:storage-locations'],
}
```

--------------------------------

### Finalize Cache Entry Upload with Twirp API

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Use the FinalizeCacheEntryUpload Twirp API to complete a multipart upload. This validates uploaded parts and atomically updates the cache entry record. Requires a GitHub Actions JWT.

```bash
curl -s -X POST http://localhost:3000/twirp/github.actions.results.api.v1.CacheService/FinalizeCacheEntryUpload \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <github-actions-jwt>" \
  -d '{"key": "npm-linux-abc123", "version": "v1"}' | jq .
```

```json
# Success
{
  "ok": true,
  "entry_id": "1234567890"
}
```

```text
# Upload not found (e.g. never created, or already finalized)
# HTTP 404: Upload not found
```

--------------------------------

### Delete Many Cache Entries

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Performs a bulk deletion of cache entries. Entries can be filtered by key, version, scope, and repository ID. If no filters are provided, all entries are deleted. This operation also asynchronously triggers storage cleanup.

```APIDOC
## DELETE /management-api/cache-entries

### Description
Bulk-deletes cache entries matching any combination of `key`, `version`, `scope`, and `repoId` filters. Asynchronously triggers storage cleanup. With no filters, deletes all entries.

### Method
DELETE

### Endpoint
/management-api/cache-entries

### Parameters
#### Query Parameters
- **key** (string) - Optional - Filter cache entries by key.
- **version** (string) - Optional - Filter cache entries by version.
- **scope** (string) - Optional - Filter cache entries by scope.
- **repoId** (string) - Optional - Filter cache entries by repository ID.

### Request Example
```bash
BASE="http://localhost:3000/management-api"
KEY="my-secret-key"

# Delete all entries for a specific key
curl -s -X DELETE "$BASE/cache-entries?key=npm-linux-abc123" \
  -H "X-Api-Key: $KEY" -w "\nHTTP %{{http_code}}\n"

# Delete all entries for a specific repository
curl -s -X DELETE "$BASE/cache-entries?repoId=123456789" \
  -H "X-Api-Key: $KEY" -w "\nHTTP %{{http_code}}\n"

# Delete everything (no filters)
curl -s -X DELETE "$BASE/cache-entries" \
  -H "X-Api-Key: $KEY" -w "\nHTTP %{{http_code}}\n"
```

### Response
#### Success Response (200)
- **(No specific fields documented)**

#### Response Example
```
HTTP 200
```
```

--------------------------------

### Delete Single Cache Entry via Management API

Source: https://context7.com/falcondev-oss/github-actions-cache-server/llms.txt

Use this endpoint to delete a specific cache entry by its UUID. This action also triggers an asynchronous cleanup of orphaned storage objects.

```bash
BASE="http://localhost:3000/management-api"
KEY="my-secret-key"
ID="550e8400-e29b-41d4-a716-446655440000"

curl -s -X DELETE "$BASE/cache-entries/$ID" -H "X-Api-Key: $KEY" -w "%{http_code}"
```