Plik mapy kodów DurableQR, format w wersji 1
Plik mapy kodów to kompletny spis kodów jednego konta DurableQR: dla każdego kodu określa, dokąd prowadzi skan. Powstał po to, aby wydrukowane kody mogły działać bez DurableQR. Resolver, czyli program, który odczytuje ten plik i odpowiada na skany według reguł z sekcji „Jak obsłużyć skan”, zwraca ten sam status, cel, obsługę ścieżki i nagłówki prywatności co DurableQR, z jednym opisanym wyjątkiem.
Format jest otwarty. Ten dokument, program sprawdzający poprawność pliku (walidator) i pliki przykładowe stanowią całą specyfikację. Decyzje projektowe opisuje ADR-0006 (docs/adr/0006-map-file-v1.md, po polsku).
Pliki
Plik mapy kodów występuje w jednym z dwóch zapisów (kodowań) o identycznej treści:
*.csv— wartości rozdzielane przecinkami,*.jsonl— JSON Lines, jedna wartość JSON w wierszu.
Każdy plik mapy kodów jest publikowany razem z <nazwa pliku>.sha256 (zob. „Suma kontrolna”).
Reguły bajtów (oba kodowania)
- UTF-8, bez znacznika kolejności bajtów.
- Wiersze kończą się LF (
\n). CR (\r) nigdy nie występuje. - Plik kończy się dokładnie jednym LF. Nie ma pustych wierszy.
- Wiersz 1 ogłasza format i wersję (zob. opis każdego kodowania).
- Jeden rekord (wiersz z danymi kodu) przypada na kod. Rekordy są posortowane rosnąco bajtowo według
stable_id, a każdystable_idwystępuje raz. - Dla danych istnieje tylko jeden dozwolony sposób zapisu (forma kanoniczna), więc te same dane dają te same bajty i sumę kontrolną.
Plik bez rekordów jest poprawny: zawiera tylko wiersz formatu (oraz, dla CSV, nagłówek kolumn).
Kolumny
Każdy rekord ma dokładnie siedem pól w tej kolejności:
| Kolumna | Typ | Znaczenie |
|---|---|---|
stable_id | 10 znaków z 0-9 A-Z, bez I L O U | Identyfikator kodu, segment ścieżki wydrukowany w kodzie QR. |
current_url | URL albo brak | Dokąd kod kieruje skan teraz. Brak wyłącznie wtedy, gdy state to deleted. |
fallback_url | URL albo brak | Awaryjny adres właściciela. Brak, gdy właściciel go nie ustawił; zawsze brak dla deleted. |
updated_at | znacznik czasu | Kiedy utworzono wersję version, czyli kiedy kod ostatnio się zmienił. |
actor | małe litery, identyfikator szesnastkowy 8-4-4-4-12 | Identyfikator użytkownika nadany przez usługę logowania; wskazuje osobę z konta, która utworzyła tę wersję. To nie jest e-mail. |
version | liczba całkowita od 1 do 9007199254740991 | Numer wersji kodu, zwiększany przy każdej zmianie. |
state | active, grace, frozen, paused, blocked albo deleted | Stan cyklu życia kodu. Zob. „Jak obsłużyć skan”. |
URL. Zaczyna się od http:// albo https:// (wielkość liter schematu jest dowolna), ma co najmniej jeden znak po //, a jego długość wynosi najwyżej 2048 bajtów UTF-8. Niedozwolone są określone znaki sterujące, odwrotne ukośniki i znaki białe zgodnie z pełną regułą formatu. URL jest przechowywany bajt w bajt tak, jak podał go właściciel: bez normalizacji i bez dodawania ukośnika.
Znacznik czasu. UTC, dokładnie YYYY-MM-DDTHH:MM:SS.mmmZ, z trzema cyframi milisekund i literalnym Z, na przykład 2026-09-01T08:15:02.041Z. Musi oznaczać rzeczywisty moment.
Historia. Plik mapy kodów w wersji 1 zawiera tylko bieżący stan każdego kodu, bez wcześniejszych miejsc docelowych. Historia zmian nie jest częścią tego formatu; historię każdego kodu odczytasz przez API i panel.
Kodowanie CSV
# durableqr-map-file format_version=1
stable_id,current_url,fallback_url,updated_at,actor,version,state
3KQ7M2XWZP,https://example.com/menu,,2026-09-01T08:15:02.041Z,0b6c4e1a-5f2d-4c8e-9a71-3d2f8e6b1c40,1,active
- Wiersz 1 jest dokładnie
# durableqr-map-file format_version=1. - Wiersz 2 zawiera dokładnie siedem nazw kolumn w podanej kolejności.
- Od wiersza 3 obowiązuje RFC 4180 z końcami LF.
- Pole jest ujęte w cudzysłowy wtedy i tylko wtedy, gdy zawiera przecinek albo cudzysłów. Cudzysłów wewnątrz pola zapisuje się podwójnie.
- Brak wartości oznacza puste pole.
versionzapisuje się dziesiętnie, bez zer wiodących.
Kodowanie JSONL
{"format":"durableqr-map-file","format_version":1}
{"stable_id":"3KQ7M2XWZP","current_url":"https://example.com/menu","fallback_url":null,"updated_at":"2026-09-01T08:15:02.041Z","actor":"0b6c4e1a-5f2d-4c8e-9a71-3d2f8e6b1c40","version":1,"state":"active"}
- Wiersz 1 jest dokładnie
{"format":"durableqr-map-file","format_version":1};format_versionjest liczbą JSON, nie tekstem. - Każdy następny wiersz jest obiektem JSON z dokładnie siedmioma kluczami w kolejności kolumn.
- Brak wartości oznacza
null, nigdy"". - Forma kanoniczna nie zawiera białych znaków między tokenami i odpowiada
JSON.stringify(record).
Wersja formatu
Resolver musi sprawdzić format_version w pierwszym wierszu, zanim odczyta resztę, i odrzucić nieznaną wersję. Ten dokument definiuje wyłącznie wersję 1.
Suma kontrolna
Suma to SHA-256 dokładnych bajtów pliku mapy kodów, razem z wierszem formatu. Jest publikowana obok pliku jako <nazwa pliku>.sha256 w formacie sha256sum: 64 małe cyfry szesnastkowe, dwie spacje, sama nazwa pliku i LF.
56434275ccc78eac27629649b77f0ee4c4ea193dc95d5c27cb2c89a4d007a5fe example.csv
Sprawdź ją bez narzędzia DurableQR: sha256sum -c example.csv.sha256, a na macOS shasum -a 256 -c example.csv.sha256.
Jak obsłużyć skan
Resolver odpowiada na skan https://<host>/<stable_id>. Identyfikator jest pierwszym segmentem ścieżki: początkowe i końcowe / są ignorowane, wszystko po następnym / jest pomijane, a parametry zapytania (query string) nie należą do ścieżki. Dopasowanie uwzględnia wielkość liter.
Dla pustego identyfikatora albo identyfikatora bez rekordu odpowiedź to 404. Dla rekordu odpowiedź zależy od state i obecności fallback_url:
state | fallback_url | Odpowiedź |
|---|---|---|
active, grace, frozen | dowolne | 302 do current_url |
paused | obecne | 302 do fallback_url |
paused | brak | 200, neutralna informacja o pauzie, bez reklam |
blocked | dowolne | 200, informacja o nadużyciu z procedurą odwołania |
deleted | zawsze brak | 404, identyczne jak dla nieistniejącego rekordu |
Każda odpowiedź resolvera ma nagłówki Cache-Control: no-store, Referrer-Policy: no-referrer oraz Content-Type: text/html; charset=utf-8, z wyjątkami infrastrukturalnymi opisanymi w źródłowej wersji angielskiej. Odpowiedź 302 ma Location ustawione bajt w bajt na URL i pustą treść odpowiedzi. Brak URL wybranej odpowiedzi oznacza 404, nigdy przekierowanie z pustym Location.
Stany grace i frozen nie zmieniają celu skanu. blocked ma pierwszeństwo przed adresem awaryjnym. Po usuniętym kodzie zostaje znacznik usunięcia (tombstone), żeby jego identyfikatora nie przydzielić ponownie.
Walidator i przykłady
Referencyjny walidator to webapp/scripts/check-map-file.mjs (Node.js 22, bez zależności poza biblioteką standardową):
cd webapp
npm run check:map-file -- path/to/map.csv path/to/map.jsonl
Sprawdza każdą regułę tego dokumentu i plik .sha256 obok każdego pliku mapy kodów; przy każdym problemie podaje numer wiersza. Kończy się kodem 0, gdy wszystkie pliki są poprawne.
Pliki przykładowe znajdują się w webapp/scripts/__fixtures__/map-file-v1/ (example.csv, example.jsonl i ich pliki .sha256). Programy eksportujące i resolvery mogą na nich sprawdzać zgodność z formatem. Cztery pliki pozostają współdzielone przez wersję angielską i polską.