v3

2026-09-26 20:41:45 +00:00 · 2026-09-06 18:34:07 +02:00
parent 062054f450
commit e0d22283c8
14 changed files with 474 additions and 30 deletions
@@ -0,0 +1,66 @@
+# v3 Breaking Changes
+
+A list of changes users and operators need to consider when upgrading from v2 to v3.
+
+## API
+
+- All note endpoints moved under `/api/v3/notes/` (was `/api/notes/`)
+- Status endpoint moved to `/api/v3/status` (was `/api/status`)
+- All request/response bodies are now **MessagePack** (`Content-Type: application/msgpack`), not JSON
+- Health check moved to `/healthz` (was `/api/live`)
+- Notes can now have **both** `views` and `expiration` set simultaneously (previously mutually exclusive)
+
+## API payload structure
+
+The wire format changed entirely. v2 used:
+
+```json
+{ "contents": "<encrypted string>", "meta": "<stringified JSON>", "views": 5, "expiration": 30 }
+```
+
+v3 uses msgpack:
+
+```
+{ meta: { views?, expiration?, extra? }, data: <encrypted bytes> }
+```
+
+- `meta.extra` holds client-opaque data (e.g. scrypt derivation params), size-limited (default 512 bytes)
+- `data` is the encrypted blob — the server never inspects its contents
+- The encrypted inner payload is itself msgpack: `{ type: "text", data: string }` or `{ type: "files", data: [{ name, mime, size, data }] }`
+
+## Environment variables
+
+| v2                  | v3                   |
+| ------------------- | -------------------- |
+| `REDIS`             | `CACHE`              |
+| `REDIS_PREFIX`      | `CACHE_PREFIX`       |
+| _(new)_             | `EXTRA_SIZE_LIMIT`   |
+
+The `CACHE` env var accepts any RESP-compatible URL (valkey or redis).
+`EXTRA_SIZE_LIMIT` (default `512`) limits the `extra` field size in bytes.
+
+## Docker / Compose
+
+- The `redis` service in docker-compose is renamed to `cache`
+- Healthcheck URL updated: `http://127.0.0.1:8000/api/live/` → `http://127.0.0.1:8000/healthz`
+- The default image stays `valkey/valkey:7-alpine` but operators can swap for any redis-compatible image
+
+## CLI (`cryptgeon` npm package)
+
+- Dropped `occulto` dependency — now uses `@noble/ciphers` + `@noble/hashes` internally
+- Encryption changed from AES to **XChaCha20-Poly1305**
+- The local `shared/` module removed — now imports from `@cryptgeon/shared` (workspace-internal)
+- Notes created with v2 (AES) are **not readable** by v3 and vice versa
+
+## Frontend
+
+- Dropped `occulto` dependency
+- Package import changed from `cryptgeon/shared` to `@cryptgeon/shared`
+- Notes created in v2 are not accessible from the v3 frontend
+
+## Storage
+
+- Cache storage format changed from JSON blobs to hashes with atomic `HINCRBY` for view counting
+- The per-note lock (`lock.rs`) is removed — no longer needed
+- Existing v2 notes in cache are **not migrated** and will be inaccessible after upgrade
+- Ensure cache is empty (or flush) before deploying v3