Plik historii celów DurableQR v1
Ten prywatny plik historii nie jest mapą ani plikiem routingu resolvera. Nie zmienia formatu map file v1.
Pobranie i autoryzacja
GET /v1/export/history używa JWT panelu i zweryfikowanego sub. GET /v1/int/export/history używa klucza API, User-Agent i aktualnego uprawnienia api_access. Żadne parametry query, w tym format i cursor, nie są obsługiwane. Nie ma CSV, publicznego URL, przechowywanego ani cyklicznego zrzutu.
Odpowiedź sukcesu to surowy JSONL, bez obudowy JSON i bez base64.
| Nagłówek | Wartość |
|---|---|
| Content-Type | application/jsonl; charset=utf-8 |
| Content-Disposition | attachment; filename="durableqr-history.jsonl" |
| X-History-File-SHA256 | suma SHA-256 dokładnych bajtów, małe cyfry hex |
| X-History-File-Records | dziesiętna liczba linii danych bez deklaracji |
| Cache-Control | no-store |
Origin panelu może odczytać te nagłówki. Klient może zapisać durableqr-history.jsonl.sha256: suma, dwie spacje, nazwa pliku i LF. Backend nie zapisuje sidecara. SHA-256 nie jest podpisem ani dowodem kompletności.
Kanoniczne bajty i pola
UTF-8 bez BOM; każda linia, także ostatnia, kończy się LF. Bez CR, pustych linii i dodatkowych spacji między tokenami JSON. Unicode i URL nie są normalizowane; obowiązuje escaping JSON. Pierwsza linia to dokładnie {"format":"durableqr-history-file","format_version":1}. Każdy zwykły rekord zawiera dokładnie osiem kluczy w tej kolejności:
| Klucz | Znaczenie |
|---|---|
| stable_id | Dokładnie 10 znaków ASCII z alfabetu 0123456789ABCDEFGHJKMNPQRSTVWXYZ |
| version | Liczba całkowita JSON od 1 do 9007199254740991 |
| url | Dokładny zapisany URL http lub https, maksymalnie 2048 bajtów UTF-8 |
| actor | UUID aktora, małe cyfry hex |
| timestamp | Dokładny zapisany czas; zwykły UTC ma YYYY-MM-DDTHH:MM:SS.mmmZ; billing zachowuje precyzję kanonicznego UTC datetime.isoformat() i +00:00 |
| rolled_back_from | null albo liczba całkowita od 1 do version minus 1 |
| transferred_from | null albo UUID nadawcy transferu, małe cyfry hex |
| source | null albo billing |
Schemat URL nie rozróżnia wielkości liter ASCII i wymaga znaku po //; U+0000 do U+001F, backslash i znaki Python str.isspace() są zabronione. Brak rollbacku lub transferu to null, nie brak klucza.
Rekordy sortowane są po ASCII stable_id, następnie liczbowo po version. Wersje obejmują 1 do przypiętej wersji META bez dziur i duplikatów. Powtarzane URL nie są deduplikowane; wersja stanu, fallbacku lub transferu nie musi oznaczać zmiany URL. Nieznane dodatkowe atrybuty są pomijane.
Brakujący lub wadliwy rekord zastępuje marker, np. {"stable_id":"2222222222","version":2,"error":"malformed_record"}. Nie ujawnia on danych wadliwego rekordu i oznacza niekompletną historię. Licznik i suma obejmują marker. Puste konto zawiera tylko deklarację i końcowy LF, records=0.
Przykład
{"format":"durableqr-history-file","format_version":1}
{"stable_id":"2222222222","version":1,"url":"https://example.org/old","actor":"11111111-1111-1111-1111-111111111111","timestamp":"2026-11-02T12:00:00.000Z","rolled_back_from":null,"transferred_from":null,"source":null}
{"stable_id":"2222222222","version":2,"url":"https://example.org/new","actor":"11111111-1111-1111-1111-111111111111","timestamp":"2026-11-02T12:01:00.000Z","rolled_back_from":null,"transferred_from":null,"source":null}
{"stable_id":"2222222222","version":3,"url":"https://example.org/old","actor":"11111111-1111-1111-1111-111111111111","timestamp":"2026-11-02T12:02:00.000Z","rolled_back_from":1,"transferred_from":null,"source":null}
Własność i spójność
Eksport obejmuje kody obecnego właściciela we wszystkich sześciu stanach, w tym frozen i deleted. Nagrobki zachowują historyczne URL w tym prywatnym pliku. Odbiorca transferu widzi wcześniejszą historię i pseudonimowych aktorów; poprzedni właściciel traci dostęp po zmianie META, nawet przy opóźnionym indeksie. Pobranej kopii nie można wycofać.
GSI1 jest ostatecznie spójny: nowy kod lub przyjęty transfer może pojawić się dopiero w kolejnym eksporcie. Licznik i suma nie dowodzą kompletności. Silnie spójne META jest sprawdzane przed i po odczycie wersji; zmiana właściciela lub wersji daje 503 całego pliku. Nie ma atomowego snapshotu wielu kodów ani blokady transferu, a zmiana po ostatnim odczycie pozostaje możliwa. Eksport można później ponowić.
Limity i błędy
Eksport synchroniczny dopuszcza najwyżej 50 kluczy GSI1, 100 wersji łącznie, 1 MiB bajtów UTF-8 pliku i 4 MiB serializowanej koperty Lambda proxy. 413 nie jest pierwszą stroną i nie ma kontynuacji; szybkie ponawianie nie zmniejszy historii. Ograniczenia są best-effort globalne dla trasy, nie dla konta: panel 0.0033/s i integrator 0.0008/s, burst 1, niezależnie od eksportu mapy.
| Status | Znaczenie |
|---|---|
| 400 | Niedozwolone query albo brak User-Agent integratora |
| 401 | Brak lub nieprawidłowa tożsamość JWT |
| 403 | Odmowa klucza API lub api_access |
| 413 | Przekroczono limit kluczy, wersji lub rozmiaru; brak pliku |
| 429 | Throttle gateway lub DynamoDB |
| 503 | Deadline, błąd SDK, wadliwy indeks lub META albo zmiana META |
Odmowy aplikacji mają standardowy JSON message i Cache-Control: no-store; aplikacyjne 429 i 503 mają Retry-After. Błędy gateway podlegają kontraktowi gateway bez obietnicy nagłówków aplikacji. Odmowa nie zawiera fragmentów pliku ani nagłówków sumy lub liczby. Nie ma publicznego fallbacku w storage.