85 lines
4.8 KiB
Markdown
85 lines
4.8 KiB
Markdown
# Sheet Relay
|
|
|
|
A local Node.js service that exposes selected Google Sheets tabs as bearer-token-protected JSON endpoints.
|
|
|
|
## Run with Docker
|
|
|
|
```powershell
|
|
docker login git.lzstealth.com
|
|
docker compose pull
|
|
docker compose up -d
|
|
docker compose logs -f
|
|
```
|
|
|
|
Open `http://localhost:3000`. The service is bound to localhost by default and pulls `git.lzstealth.com/lzstealth/google-sheets-to-api:latest`. Its configuration is persisted in `data/config.json` beside the Compose file, so it survives image updates and container replacements.
|
|
|
|
Pushes to `main` publish both the immutable commit tag and `latest` through Gitea Actions. The workflow uses the global `PACKAGE_REGISTRY_USERNAME` and `PACKAGE_REGISTRY_PASSWORD` secrets; grant that account permission to publish packages for the `lzstealth` organization.
|
|
|
|
Stop it with:
|
|
|
|
```powershell
|
|
docker compose down
|
|
```
|
|
|
|
## Reverse proxy deployment
|
|
|
|
The Compose service listens only at `127.0.0.1:3000`. Put your existing reverse proxy in front of it for HTTPS, public routing, access logs, and any network policy. Configure that proxy's upstream as `http://127.0.0.1:3000` and forward the original `Host`, client address, and scheme headers.
|
|
|
|
Check container health and logs with:
|
|
|
|
```powershell
|
|
docker compose ps
|
|
docker compose logs -f sheet-relay
|
|
```
|
|
|
|
## Run with Node
|
|
|
|
```powershell
|
|
npm install
|
|
npm start
|
|
```
|
|
|
|
Open `http://localhost:3000`. The first launch creates `data/config.json` and prints a one-time admin token. Keep this token private; use it to unlock the configuration console.
|
|
|
|
## Configure
|
|
|
|
1. Choose **API key** for public/readable sheets, or **Service account** for private sheets.
|
|
2. With a service account, share each spreadsheet with the `client_email` in its JSON credential as a Viewer.
|
|
3. Keep the default 45 requests per minute to leave a buffer below a 50 RPM allowance, or set the quota that applies to your Google project.
|
|
4. Load a spreadsheet ID, check the tabs to expose, then publish the endpoint. Sheet Relay generates its bearer token automatically; copy it from the endpoint controls.
|
|
|
|
## Consume
|
|
|
|
```powershell
|
|
curl http://localhost:3000/api/v1/YOUR_PUBLICATION_ID -H "Authorization: Bearer YOUR_ENDPOINT_TOKEN"
|
|
```
|
|
|
|
Only the selected tabs are returned. Responses use a configurable short cache, reducing Google API calls and respecting the shared rate limiter.
|
|
|
|
Each endpoint can return either raw sheet rows or objects keyed from the first row's headers. Object output requires non-empty, unique headers. It can also limit reads with an A1 range such as `A1:H500`, cap rows per sheet, and omit blank rows. Editing any of these options clears that endpoint's cached response immediately.
|
|
|
|
Google `429` and `5xx` responses retry up to two times. Retries honor Google's `Retry-After` header when present, otherwise use 1-second then 2-second backoff, with every retry passing through the same configured credential rate limiter.
|
|
|
|
## Operations
|
|
|
|
The **Operations** page provides service uptime, endpoint health, endpoint and tab-cache counts, and the latest 50 API request outcomes. It retains 500 entries, supports endpoint/status/result filters, and can clear the retained log. Request logs record the endpoint ID, status, cache/stale state, duration, and client address; they never store bearer tokens.
|
|
|
|
Use **Refresh** to update an endpoint cache immediately, **Disable** to return `503` without deleting its setup, or **Rotate token** to generate and copy a replacement token. Rotation invalidates the previous token immediately. Background cache refresh can be enabled per endpoint.
|
|
|
|
Use **Export redacted config** to create a transferable configuration without Google secrets, endpoint tokens, or the admin token. Importing replaces the current configuration; credentials have no secrets, endpoints receive new tokens, and endpoints remain disabled until you complete credential setup and explicitly enable them.
|
|
|
|
The public health check is available at:
|
|
|
|
```text
|
|
GET /health
|
|
```
|
|
|
|
Prometheus-compatible operational counters are available at `GET /metrics`. This endpoint requires the `x-admin-token` header.
|
|
|
|
Browser-origin requests are denied by default. Use `*` in the **Operations** page to allow all origins, or enter exact origins such as `https://app.example.com`, one per line, to allow selected browser clients. Server-to-server API clients are unaffected because they do not send an `Origin` header.
|
|
|
|
When the service is behind a reverse proxy, set **Trusted reverse proxy hops** to the number of proxies directly in front of it, typically `1`. This allows the request audit log to use the original client address from forwarded headers. Leave it at `0` unless the proxy path is trusted.
|
|
|
|
## Security notes
|
|
|
|
`data/config.json` contains Google credentials and endpoint tokens. It is intentionally ignored by Git; protect the machine and back up the file securely. Put this service behind HTTPS when it is reachable beyond localhost. |