feat: proxy unknown requests to default GitHub ACTIONS_RESULTS_URL & revive v1 support

Author: LouisHaftmann

.env

@@ -1,7 +1,5 @@
 API_BASE_URL=http://localhost:3000
 DEBUG=true
-CA_KEY_PATH=./certs/key.pem
-CA_CERT_PATH=./certs/cert.pem
 
 # filesystem
 STORAGE_DRIVER=filesystem

.github/workflows/ci-cd.yml

@@ -50,16 +50,10 @@ jobs:
       - name: pnpm install
         uses: falcondev-it/.github/actions/pnpm-install@master
 
-      - run: touch mock.key
-      - run: touch mock.crt
-
       - run: pnpm run test:run
         env:
           VITEST_DB_DRIVER: ${{ matrix.db-driver }}
           VITEST_STORAGE_DRIVER: ${{ matrix.storage-driver }}
-          DISABLE_PROXY: true
-          CA_CERT_PATH: mock.crt
-          CA_KEY_PATH: mock.key
 
   deploy:
     if: github.event.ref == 'refs/heads/dev'

.gitignore

@@ -11,5 +11,4 @@ data/
 .idea
 .DS_Store
 tests/temp/
-certs/*
-!certs/.gitkeep
+actions-runner/

README.md

@@ -12,28 +12,16 @@ This is a drop-in replacement for the official GitHub hosted cache server. It is
 ```yaml
 services:
   cache-server:
-    image: ghcr.io/falcondev-oss/github-actions-cache-server:latest
+    image: ghcr.io/falcondev-oss/github-actions-cache-server
     ports:
       - '3000:3000'
-      - '8000:8000'
     environment:
       API_BASE_URL: http://localhost:3000
-      CA_KEY_PATH: /run/secrets/ca_key
-      CA_CERT_PATH: /run/secrets/ca_cert
     volumes:
       - cache-data:/app/.data
-    secrets:
-      - ca_key
-      - ca_cert
 
 volumes:
   cache-data:
-
-secrets:
-  ca_key:
-    file: ./key.pem
-  ca_cert:
-    file: ./cert.pem
 ```
 
 ## Documentation

certs/.gitkeep

@@ -1,9 +1,9 @@
 ---
 title: Getting Started
-description: Deploy the GitHub Actions Cache Server using Docker and use it with self-hosted runners
+description: Deploy the Cache Server with Docker and self-hosted runners
 ---
 
-The cache server comes as a Docker image and can be deployed using Docker Compose or Kubernetes.
+The cache server is available as a Docker image and can be deployed via Docker Compose or Kubernetes.
 
 ## 1. Deploying the Cache Server
 
@@ -13,25 +13,13 @@ services:
     image: ghcr.io/falcondev-oss/github-actions-cache-server:latest
     ports:
       - '3000:3000'
-      - '8000:8000'
     environment:
       API_BASE_URL: http://localhost:3000
-      CA_KEY_PATH: /run/secrets/ca_key
-      CA_CERT_PATH: /run/secrets/ca_cert
     volumes:
       - cache-data:/app/.data
-    secrets:
-      - ca_key
-      - ca_cert
 
 volumes:
   cache-data:
-
-secrets:
-  ca_key:
-    file: ./key.pem
-  ca_cert:
-    file: ./cert.pem
 ```
 
 ### Environment Variables
@@ -42,14 +30,6 @@ secrets:
 
 The base URL of your cache server. This needs to be accessible by your runners as it is used for making API requests and downloading cached files.
 
-#### `CA_KEY_PATH`
-
-Path to the CA key. This is used for proxying HTTPS requests which is needed for intercepting cache requests.
-
-#### `CA_CERT_PATH`
-
-Path to the CA certificate. This is used for proxying HTTPS requests which is needed for intercepting cache requests.
-
 #### `STORAGE_DRIVER`
 
 - Default: `filesystem`
@@ -78,7 +58,7 @@ variant: subtle
 ---
 ::
 
-#### `CACHE_CLEANUP_OLDER_THAN_DAYS`
+#### `CLEANUP_OLDER_THAN_DAYS`
 
 - Default: `90`
 
@@ -96,11 +76,6 @@ The cron schedule for running the cache cleanup job.
 
 The cron schedule for running the upload cleanup job. This job will delete any dangling (failed or incomplete) uploads.
 
-#### `PROXY_PORT`
-
-- Default: `8000`
-
-The port the proxy server should listen on.
 
 #### `NITRO_PORT`
 
@@ -116,30 +91,48 @@ The directory to use for temporary files.
 
 ## 2. Setup with Self-Hosted Runners
 
-### Generate CA Key and Certificate
+Set the `ACTIONS_RESULTS_URL` on your runner to the API URL (with a trailing slash).
 
-```bash
-openssl req -x509 -newkey rsa:4096 -keyout key.pem -out cert.pem -days 3650 -nodes
-```
+::u-alert
+---
+icon: 'tabler:alert-triangle'
+class: ring-amber-400
+color: amber
+description: Ensure ACTIONS_RESULTS_URL ends with a trailing slash.
+variant: subtle
+---
+::
 
-This will create a `key.pem` and `cert.pem` file in the current directory. These files need to be mounted into the cache server container.
+### Runner Configuration
 
-### Update the Dockerfile of your runner image
+For Docker:
 
 ```dockerfile [Dockerfile]
-# Add the CA certificate to trusted certificates
-RUN sudo apt-get install -y ca-certificates
-RUN echo "<YOUR GENERATED CERTIFICATE>" | sudo tee /usr/local/share/ca-certificates/cache-server-ca.crt
-RUN sudo update-ca-certificates
+FROM ghcr.io/actions/actions-runner:latest
+# Modify runner binary to retain custom ACTIONS_RESULTS_URL
+RUN sed -i 's/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x55\x00\x52\x00\x4C\x00/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x4F\x00\x52\x00\x4C\x00/g' /home/runner/bin/Runner.Worker.dll
+```
+
+For Bare Metal, similar commands apply:
+
+::code-group
 
-# Configure NodeJS to use the CA certificate
-ENV NODE_EXTRA_CA_CERTS=/usr/local/share/ca-certificates/cache-server-ca.crt
+```bash [Linux]
+sed -i 's/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x55\x00\x52\x00\x4C\x00/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x4F\x00\x52\x00\x4C\x00/g' /path_to_your_runner/bin/Runner.Worker.dll
+```
+
+```bash [MacOS]
+gsed -i 's/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x55\x00\x52\x00\x4C\x00/\x41\x00\x43\x00\x54\x00\x49\x00\x4F\x00\x4E\x00\x53\x00\x5F\x00\x52\x00\x45\x00\x53\x00\x55\x00\x4C\x00\x54\x00\x53\x00\x5F\x00\x4F\x00\x52\x00\x4C\x00/g' /path_to_your_runner/bin/Runner.Worker.dll
+```
 
-# Configure proxy
-ENV http_proxy=http://<your cache server>:<PROXY_PORT>
-ENV https_proxy=http://<your cache server>:<PROXY_PORT>
+```bash [Windows]
+[byte[]] -split (((Get-Content -Path ./bin/Runner.Worker.dll -Encoding Byte) | ForEach-Object ToString X2) -join '' -Replace '41004300540049004F004E0053005F0052004500530055004C00540053005F00550052004C00','41004300540049004F004E0053005F0052004500530055004C00540053005F004F0052004C00' -Replace '..', '0x$& ') | Set-Content -Path /path_to_your_runner/bin/Runner.Worker.dll -Encoding Byte
 ```
 
+::
+
+This patch prevents the runner from overwriting your custom ACTIONS_RESULTS_URL.
+
 ## 3. Using the Cache Server
 
 There is no need to change any of your workflows! 🔥

docs/content/1.getting-started/1.index.md

@@ -1,6 +1,40 @@
 ---
 title: How it works
-description: ''
+description: How the cache server integrates with GitHub Actions
 ---
 
-The cache server acts as a proxy for the actions runner. We forward all cache related requests to our cache server implementation and passthrough any non-cache related requests to the original server.
+## 1. Reverse-Engineering
+
+We replicate the official cache API by examining runner requests and the actions/cache source. See GitHub docs on cache keys.
+
+## 2. Configuring the Runner
+
+The runner overrides ACTIONS_RESULTS_URL with its internal endpoint. We patched the binary by replacing "ACTIONS_RESULTS_URL" with "ACTIONS_RESULTS_ORL" (keeping the same length) to allow a custom cache URL.
+
+```c#
+var systemConnection = ExecutionContext.Global.Endpoints.Single(x => string.Equals(x.Name, WellKnownServiceEndpointNames.SystemVssConnection, StringComparison.OrdinalIgnoreCase));
+Environment["ACTIONS_RUNTIME_URL"] = systemConnection.Url.AbsoluteUri;
+Environment["ACTIONS_RUNTIME_TOKEN"] = systemConnection.Authorization.Parameters[EndpointAuthorizationParameters.AccessToken];
+if (systemConnection.Data.TryGetValue("CacheServerUrl", out var cacheUrl) && !string.IsNullOrEmpty(cacheUrl))
+{
+    Environment["ACTIONS_CACHE_URL"] = cacheUrl;
+}
+if (systemConnection.Data.TryGetValue("PipelinesServiceUrl", out var pipelinesServiceUrl) && !string.IsNullOrEmpty(pipelinesServiceUrl))
+{
+    Environment["ACTIONS_RUNTIME_URL"] = pipelinesServiceUrl;
+}
+if (systemConnection.Data.TryGetValue("GenerateIdTokenUrl", out var generateIdTokenUrl) && !string.IsNullOrEmpty(generateIdTokenUrl))
+{
+    Environment["ACTIONS_ID_TOKEN_REQUEST_URL"] = generateIdTokenUrl;
+    Environment["ACTIONS_ID_TOKEN_REQUEST_TOKEN"] = systemConnection.Authorization.Parameters[EndpointAuthorizationParameters.AccessToken];
+}
+if (systemConnection.Data.TryGetValue("ResultsServiceUrl", out var resultsUrl) && !string.IsNullOrEmpty(resultsUrl))
+{
+    Environment["ACTIONS_RESULTS_URL"] = resultsUrl;
+}
+
+if (ExecutionContext.Global.Variables.GetBoolean("actions_uses_cache_service_v2") ?? false)
+{
+    Environment["ACTIONS_CACHE_SERVICE_V2"] = bool.TrueString;
+}
+```

docs/content/1.getting-started/4.how-it-works.md

@@ -2,9 +2,9 @@ title: GitHub Actions Cache Server
 description: Easily deploy your own GitHub actions cache without needing to change any workflow files!
 navigation: false
 hero:
-  title: Self-Hosted Cache Server<br>for GitHub Actions
+  title: Self-Hosted Cache Server for GitHub Actions
   description: Easily deploy your own GitHub actions cache without needing to change any workflow files!
-  orientation: vertical
+  orientation: horizontal
   links:
     - label: Get started
       icon: i-heroicons-arrow-right-20-solid
@@ -18,25 +18,13 @@ hero:
         image: ghcr.io/falcondev-oss/github-actions-cache-server:latest
         ports:
           - '3000:3000'
-          - '8000:8000'
         environment:
           API_BASE_URL: http://localhost:3000
-          CA_KEY_PATH: /run/secrets/ca_key
-          CA_CERT_PATH: /run/secrets/ca_cert
         volumes:
           - cache-data:/app/.data
-        secrets:
-          - ca_key
-          - ca_cert
 
     volumes:
       cache-data:
-
-    secrets:
-      ca_key:
-        file: ./key.pem
-      ca_cert:
-        file: ./cert.pem
     ```
 features:
   items:

docs/content/index.yml

@@ -15,7 +15,7 @@ type: application
 # This is the chart version. This version number should be incremented each time you make changes
 # to the chart and its templates, including the app version.
 # Versions are expected to follow Semantic Versioning (https://semver.org/)
-version: 0.2.0
+version: 0.3.0
 
 # This is the version number of the application being deployed. This version number should be
 # incremented each time you make changes to the application. Versions are not expected to

install/kubernetes/github-actions-cache-server/Chart.yaml

@@ -46,9 +46,6 @@ spec:
             - name: cache
               containerPort: 3000
               protocol: TCP
-            - name: proxy
-              containerPort: 8000
-              protocol: TCP
           livenessProbe:
             {{- toYaml .Values.livenessProbe | nindent 12 }}
           readinessProbe:
@@ -65,8 +62,6 @@ spec:
           env:
             - name: PORT
               value: "3000"
-            - name: PROXY_PORT
-              value: "8000"
             - name: API_BASE_URL
               value: {{ default $internalApiBaseUrl .Values.apiBaseUrl }}
           {{- with .Values.env }}

install/kubernetes/github-actions-cache-server/templates/deployment.yaml

@@ -11,9 +11,5 @@ spec:
       targetPort: cache
       protocol: TCP
       name: cache
-    - port: {{ .Values.service.proxyPort }}
-      targetPort: proxy
-      protocol: TCP
-      name: proxy
   selector:
     {{- include "github-actions-cache-server.selectorLabels" . | nindent 4 }}

install/kubernetes/github-actions-cache-server/templates/service.yaml

@@ -45,7 +45,6 @@ securityContext:
 service:
   type: ClusterIP
   port: 80
-  proxyPort: 8000
 
 ingress:
   enabled: false

install/kubernetes/github-actions-cache-server/values.yaml

@@ -13,12 +13,8 @@ const envSchema = z.object({
   STORAGE_DRIVER: z.string().toLowerCase().default('filesystem'),
   DB_DRIVER: z.string().toLowerCase().default('sqlite'),
   DEBUG: booleanSchema.default('false'),
-  PROXY_PORT: portSchema.default(8000),
   NITRO_PORT: portSchema.default(3000),
-  CA_KEY_PATH: z.string(),
-  CA_CERT_PATH: z.string(),
   TEMP_DIR: z.string().default(tmpdir()),
-  DISABLE_PROXY: booleanSchema.default('false'),
 })
 
 const parsedEnv = envSchema.safeParse(process.env)

lib/env.ts

@@ -35,7 +35,6 @@
     "execa": "^9.5.2",
     "h3": "npm:[email protected]",
     "kysely": "^0.27.5",
-    "mockttp": "^3.16.0",
     "mysql2": "^3.12.0",
     "nitropack": "npm:[email protected]",
     "pg": "^8.13.1",