You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs(readme): split docs and expand operational guidance
Create dedicated docs pages for developer workflow and API endpoints, and turn README into a concise landing page with quick start.
Add Dockerfile usage example, extended redeployment pitfall explanation, and under-the-hood behavior summary.
Update AGENTS documentation index to include the new docs pages.
Extremely fast cache-first dynamic HTTP proxy cacher with revalidate-under-the-hood strategy (SWR + warm up).
7
-
8
-
For extreme performance on SSR like next.js/nuxt.js or any other "slow" server side rendering.
9
-
10
-
## Mantras
11
-
12
-
- For non-bypass URLs, always serves from instant cache, which revalidates in background
13
-
- Only dynamic responses are cached which have one of headers `Cache-Control: no-cache` or `Cache-Control: no-store` or `Cache-Control: max-age=0` (or their combination)
14
-
- Adds headers for debug, e.g. x-wait0: hit|miss|bypass|ignore-by-cookie|ignore-by-status header to response to indicate cache status
15
-
- Never changes Cache-Control or any existing headers from origin
16
-
- Only GET requests are cached
17
-
- Only 2xx responses are cached, if non-2xx happens, cache is instantly invalidated
18
-
- Simple, fast & lightweight, one file configuration
19
-
- Bypass if some cookie exists (you define name) to prevent cookie-specific issues
20
-
- No query/fragment in cache key to prevent cache thrashing, only path is used as cache key.
21
-
- When wait0 starts - cache is empty (even disk one).
22
-
- Optionally wait0 can warm up from sitemaps so first users get hits!
3
+
> Ultra-fast cache-first reverse proxy for dynamic SSR workloads.
23
4
5
+
`wait0` serves cached HTML instantly and revalidates in the background.
6
+
It is designed for Next.js/Nuxt.js and other dynamic origins where latency and origin offload matter.
In Nuxt/Next and similar SSR setups, HTML pages often reference versioned static assets (usually hashed filenames). After a redeploy those filenames can change, and you typically **should not** keep old static files around.
132
-
133
-
If old HTML is still cached in wait0, it may reference static files that are no longer available (or not yet present in a given CDN/geo). This can cause broken pages after redeploy.
134
-
135
-
To avoid this, invalidate all wait0 caches, by enforcing a docker service restart:
136
-
137
-
e.g. in compose:
138
-
139
-
```yaml
140
-
docker compose restart wait0
43
+
```bash
44
+
docker run --rm -p 8082:8082 \
45
+
-v "$(pwd)/wait0.yaml:/wait0.yaml:ro" \
46
+
devforth/wait0:latest
141
47
```
142
48
143
-
Both RAM and disk caches are cleared on restart, so all stale HTML is removed and new HTML with correct static asset references is cached.
49
+
3. Alternative: build a tiny wrapper image with your config baked in.
144
50
145
-
If you need to pre-warm cache after redeploy, it is recommended to use a sitemap.
51
+
`Dockerfile`:
146
52
147
-
## Invalidation API
53
+
```dockerfile
54
+
FROM devforth/wait0:latest
55
+
COPY wait0.yaml /wait0.yaml
56
+
EXPOSE 8082
57
+
```
148
58
149
-
`wait0` exposes an authenticated async invalidation endpoint:
59
+
Build and run:
150
60
151
-
- `POST /wait0/invalidate`
152
-
- `Authorization: Bearer <token>`
153
-
- `Content-Type: application/json`
61
+
```bash
62
+
docker build -t my-wait0:latest .
63
+
docker run --rm -p 8082:8082 my-wait0:latest
64
+
```
154
65
155
-
Request body:
66
+
4. Send requests through wait0:
156
67
157
-
```json
158
-
{
159
-
"paths": ["/products/123", "/"],
160
-
"tags": ["product:123", "homepage"]
161
-
}
68
+
```bash
69
+
curl -i http://localhost:8082/
162
70
```
163
71
164
-
Notes:
165
-
- `paths`, `tags`, or both can be provided.
166
-
- Path inputs are normalized to wait0 cache keys (path-only; query/fragment are ignored).
167
-
- Tag invalidation matches cached entries where origin response headers contain `X-Wait0-Tag` (supports repeated and comma-separated values).
168
-
- Invalidation runs in the background and returns `202 Accepted` immediately.
169
-
- After invalidation, wait0 automatically re-crawls affected paths to refill cache with fresh origin responses.
72
+
First request is usually `X-Wait0: miss`, subsequent requests are usually `X-Wait0: hit`.
Returns `202 Accepted` and processes invalidation asynchronously.
85
+
Authorization is scope-based (`invalidation:write`) to support least-privilege tokens and future API growth without changing token model.
181
86
182
-
## Under the hood
87
+
## Documentation
183
88
184
-
- First it checks RAM-cache for the URL, if exists, serves it instantly and revalidates in background if revalidate condition is met.
185
-
- Revalidated content calculates quick hash and check hash in storage, if hash is different, updates cache with new content and hash (read-safe, write-atomic)
186
-
- If RAM storage is full, it moves 10% of least recently used items to disk storage (based on leveldb) and removes them from RAM, if disk storage is full, it evicts 10% of least recently used items - deletes them from disk storage. Then it puts new item to RAM storage (by prechecking if it can fit in RAM, if not, it directly puts to disk storage if it can fit)
187
-
- if some storage is overflowin it drops log warning, not ofter then once per minute.
SSR frameworks like Next.js/Nuxt usually output versioned static asset names (for example, `app.abc123.js`).
97
+
After a redeploy, HTML references switch to new filenames (for example, `app.def456.js`), and old files are commonly removed.
192
98
193
-
```bash
194
-
make test
195
-
go run ./cmd/wait0 -config ./debug/wait0.yaml
196
-
```
197
-
198
-
Testing and coverage gates:
99
+
If stale HTML is still cached, clients can receive pages that point to missing assets. Typical symptoms are broken UI, hydration failures, and partial renders.
199
100
200
-
```bash
201
-
# show all available targets
202
-
make help
203
-
204
-
# full local quality gate (lint + tests + race + coverage threshold + build)
205
-
make ci-check
206
-
207
-
# common commands
208
-
make build
209
-
make test
210
-
make test-race
211
-
make lint
212
-
make fmt
213
-
make coverage
214
-
make dev
215
-
```
101
+
To reduce this risk, `wait0` clears disk cache on startup by default (`WAIT0_INVALIDATE_DISK_CACHE_ON_START=true`).
102
+
That behavior makes rollout safer because old HTML is not reused across deploy generations.
0 commit comments