Skip to content

docs: correct env claims, the Postman full tier, and Quick Start model examples #262

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
jsugg merged 1 commit into from
Jul 15, 2026
+9 −6
Merged

docs: correct env claims, the Postman full tier, and Quick Start model examples #262

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions DEVELOPMENT.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -507,7 +507,7 @@ method, or protocol.
| `CLUSTER_MAX_CRASHES` | No | `5` | Maximum unexpected worker exits allowed inside the crash window before the primary exits non-zero. |
| `CLUSTER_SHUTDOWN_TIMEOUT_MS` | No | `10000` | Time the cluster primary waits for worker disconnect during shutdown before forcing exit. |
| `REDIS_URL` | No | unset | Shared Redis URL used automatically for rate limiting when `RATE_LIMIT_STORE=auto` and no explicit `RATE_LIMIT_REDIS_URL` is provided. |
| `SCRAPER_REQUEST_TIMEOUT_MS` | No | `10000` | Timeout for outbound page fetches and provider HTTP calls. |
| `SCRAPER_REQUEST_TIMEOUT_MS` | No | `10000` | Timeout for outbound page fetches and provider HTTP calls. The Render service raises this to `90000`: hosted vision models routinely take more than 10s per image, and the free-tier instance is slower still. |
| `SCRAPER_MAX_REDIRECTS` | No | `5` | Redirect limit for outbound page fetches. |
| `SCRAPER_MAX_CONTENT_LENGTH_BYTES` | No | `2097152` | Maximum response body size accepted when scraping HTML. |

Expand Down Expand Up @@ -610,7 +610,7 @@ At least one provider must be configured at startup: `REPLICATE_API_TOKEN`, Azur
- `/api/health` is the readiness signal used by Render. It returns `200` while the instance is ready and `503` once graceful shutdown begins.
- Status routes use their own limiter so health probes are protected without sharing the main API request budget.
- Clustered mode (`WORKER_COUNT > 1`) requires a Redis-backed limiter. Startup validation fails fast if clustered mode is enabled without `RATE_LIMIT_STORE=redis|auto` and a resolvable Redis endpoint.
- The current Render deployment keeps `RATE_LIMIT_REDIS_TOPOLOGY=external`, so the future pod-local Redis path is explicitly disabled for now.
- The current Render deployment runs the `external` topology — it does not set `RATE_LIMIT_REDIS_TOPOLOGY` at all, and `external` is the code default (`config/rateLimitStore.js`) — so the future pod-local Redis path is inactive for now.
- Horizontal instance scaling should use an external/shared Redis-backed limiter, and `STATUS_RATE_LIMIT_MAX` should be sized for the aggregate health-probe budget across instances.
- The future `RATE_LIMIT_REDIS_TOPOLOGY=unit-local` mode is meant for a Docker/Kubernetes-style resilient unit where several worker processes intentionally share one pod-local Redis instance.
- Redis-backed limiter errors fail open at request time to preserve availability, but startup still fails fast when Redis is explicitly required and unreachable during bootstrap.
Expand Down
8 changes: 5 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,10 +270,12 @@ GET `/api/accessibility/description` or `/api/v1/accessibility/description`
- fast providers return `200` with the description array immediately
- slow async providers such as `replicate` can return `202` with `jobId`, `status`, `pollAfterMs`, and `statusUrl`

Example:
Example — replace `<configured-model>` with a provider you configured in `.env`.
A provider registers only when its keys are set, and an unregistered one returns
`400 UNKNOWN_MODEL`:

```bash
curl -sk "https://localhost:8443/api/accessibility/description?image_source=https%3A%2F%2Fwww.google.com%2Fimages%2Fbranding%2Fgooglelogo%2F1x%2Fgooglelogo_color_272x92dp.png&model=replicate"
curl -sk "https://localhost:8443/api/accessibility/description?image_source=https%3A%2F%2Fwww.google.com%2Fimages%2Fbranding%2Fgooglelogo%2F1x%2Fgooglelogo_color_272x92dp.png&model=<configured-model>"
```

GET `/api/accessibility/description-jobs/:jobId` or `/api/v1/accessibility/description-jobs/:jobId`
Expand Down Expand Up @@ -304,7 +306,7 @@ GET `/api/accessibility/descriptions` or `/api/v1/accessibility/descriptions`
Example:

```bash
curl -sk "https://localhost:8443/api/accessibility/descriptions?url=https%3A%2F%2Fdeveloper.chrome.com%2F&model=replicate"
curl -sk "https://localhost:8443/api/accessibility/descriptions?url=https%3A%2F%2Fdeveloper.chrome.com%2F&model=<configured-model>"
```

GET `/api/accessibility/page-description-jobs/:jobId` or `/api/v1/accessibility/page-description-jobs/:jobId`
Expand Down
3 changes: 2 additions & 1 deletion docs/postman-standards.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,8 @@ Use the Postman/Newman layer for external HTTP contract validation, not for re-t
- Fast deterministic checks required on pull requests
- Covers core health/docs/routing, protected-endpoint auth, and one representative provider path
- `full`
- Full deterministic harness for `main` and `production`
- Full deterministic harness. Runs on manual dispatch, weekly schedule, and paths-filtered push/PR to `main` (`Local Provider Integration`)
- Not run on `production` — CI runs the `smoke` tier there
- Adds broader contract, negative-path, and page-description coverage
- `live`
- Manual or scheduled validation against real providers
Expand Down
Loading