Nastanak zapisa i početak njegovog važenja treba razdvojiti

Gradio sam tri sistema u nepovezanim oblastima: 2020. godine sistem za carinsko fakturisanje, 2022. terminale za novčane doznake i 2023. platformu za sastanke. U svakom je trebalo donijeti istu odluku.

Proizvodi, timovi i stackovi bili su različiti, ali se dizajn svaki put sveo na isto pitanje: od kada ovaj zapis važi? Trenutak u kojem je upisan i trenutak od kojeg obavezuje nisu uvijek isti.

Većina modela podataka to ne pita. Red koji postoji smatra se stvarnim. To funkcioniše dok se trenutak nastanka i trenutak važenja ne razdvoje. Tada model zakaže, a da se ne javi nijedna greška.

Svaki sistem koji izdaje dokumente prije ili kasnije naleti na ovo, a većina naleti prekasno.

Šabloni se mijenjaju: ispravi se raspored, ažurira pravna napomena ili zamijeni logo. Onda neko otvori dokument izdat prije dvije godine i vidi ovogodišnji šablon, s ovogodišnjim pravnim tekstom, na zapisu koji je potpisan pod drugim uslovima.

Nije se javila nijedna greška i nijedan test nije pao. Dokument se jednostavno promijenio, a arhiva više nije pokazivala ono što je izdato.

Isti problem javlja se svugdje gdje se nastanak i važenje mogu razići, na primjer kod kupona odštampanog bez mreže ili kod table koja postoji samo kao screenshot.

Zahtjev za carinsko fakturisanje bio je apsolutan: izdata faktura nikad se ne smije promijeniti.

Uobičajeno rješenje je čuvati podatke fakture i renderovati dokument kad ga neko zatraži. To je prirodan dizajn, ali ovdje ne radi, jer dokument koji se renderuje na zahtjev u trenutku čitanja zavisi od tri stvari: podataka, šablona i koda za renderovanje. Ako se promijeni bilo šta od toga, mijenja se i svaki stari dokument.

Zato sistem u trenutku izdavanja renderuje dokument i čuva ga kao nepromjenjiv HTML. Kasnije izmjene šablona ne diraju ništa što je već izdato.

U Node.js-u i PostgreSQL-u to izgleda otprilike ovako:

1async function issueInvoice(db, invoiceId) {2  return db.tx(async (t) => {3    const invoice = await t.one(4      'SELECT * FROM invoices WHERE id = $1 FOR UPDATE',5      [invoiceId],6    )7    if (invoice.issued_at) throw new Error('Invoice already issued')8 9    const template = await t.one(10      'SELECT * FROM invoice_templates WHERE active',11    )12    const html = renderInvoice(invoice, template)13 14    await t.none(15      `INSERT INTO issued_invoices (invoice_id, html, issued_at)16       VALUES ($1, $2, now())`,17      [invoiceId, html],18    )19    await t.none(20      'UPDATE invoices SET issued_at = now() WHERE id = $1',21      [invoiceId],22    )23  })24}

Izdata faktura se onda čita tako što se vrati sačuvani HTML, a renderInvoice se više nikad ne poziva.

Tako je definicija dokumenta odvojena od izdatog dokumenta, pa se šablon može dalje mijenjati, a historija ostaje netaknuta.

Druga korist lako se previdi: zamrznuti dokument više ne zavisi od toga hoće li kod za renderovanje i ubuduće biti ispravan. Da se dokumenti renderuju na zahtjev, greška koja se sljedeće godine uvuče u formatiranje datuma retroaktivno bi izmijenila svaku fakturu koja je ikad izdata. Kad je dokument zamrznut, buduća greška može oštetiti samo buduće dokumente.

Nepromjenjivost koja postoji samo u kodu aplikacije je konvencija, a nju može prekršiti već sljedeća osoba koja pokrene skriptu za migraciju. Ako želite da to bude pravilo, neka izmjenu odbije sama baza:

1CREATE FUNCTION reject_change() RETURNS trigger AS $$2BEGIN3  RAISE EXCEPTION 'issued invoices cannot be changed';4END;5$$ LANGUAGE plpgsql;6 7CREATE TRIGGER issued_invoices_immutable8BEFORE UPDATE OR DELETE ON issued_invoices9FOR EACH ROW EXECUTE FUNCTION reject_change();

Terminali za novčane doznake imali su suprotan problem. Primalac podiže gotovinu na benzinskoj pumpi pomoću koda s kupona. Terminal mora raditi i kad mreža ne radi, ali kupon isplaćen dvaput jedina je greška od koje se gubi stvarni novac.

Ako su nastanak i važenje isti događaj, nema dobrog izlaza. Ili terminal odbija štampati bez veze i prestaje biti koristan baš tamo gdje je veza najlošija, ili štampa kupon koji se odmah može isplatiti, pa ste napravili način da se isplati novac za koji centralni sistem još ne zna.

Kad se ta dva događaja razdvoje, dilema nestaje. Kupon se odštampa, ali još ne važi, a važeći postaje kad to sistem potvrdi: automatski kad se veza vrati ili ručno preko operatera, kojem sistem javlja da postoji neaktiviran kupon.

Na terminalu, u Kotlinu, to su dva stanja i postupak koji se pokrene kad se mreža vrati:

1enum class CouponState { PRINTED, VALID }2 3data class Coupon(4    val code: String,5    val state: CouponState,6    val printedAt: Instant,7    val validatedAt: Instant? = null,8)9 10class CouponSync(11    private val dao: CouponDao,12    private val api: CouponApi,13) {14    // printing only records that the coupon exists15    fun print(code: String): Coupon =16        Coupon(code, CouponState.PRINTED, Instant.now())17            .also { dao.insert(it) }18 19    // validity comes from the system, never from the terminal alone20    suspend fun validatePending() {21        dao.findByState(CouponState.PRINTED).forEach { coupon ->22            api.register(coupon.code)23            dao.markValid(coupon.code, Instant.now())24        }25    }26 27    // what the operator is shown28    fun pending(): List<Coupon> = dao.findByState(CouponState.PRINTED)29}

U ovom kodu je važno to što je međustanje sačuvano i vidljivo. Sistem zna da je kupon nastao, a još nije potvrđen, pa se to stanje ne može izgubiti a da niko ne primijeti. Kupon koji je odštampan, a još ne važi, sistemu je poznat i ima operatera koji se njime bavi.

Te dvije greške nisu jednako skupe i to odlučuje na koju stranu pogriješiti: bolje je da kupon ostane neupotrebljiv nego da se isplati dvaput. Neupotrebljiv kupon je neprijatnost koju neko može riješiti, a kupon isplaćen dvaput je novac kojeg više nema.

Platformi za sastanke trebala je bijela tabla s kojom se može raditi i nakon što sastanak završi. Uobičajeno rješenje je screenshot: kad se sesija završi, canvas se sačuva kao slika. Tabla tada postoji, u smislu da o njoj postoji zapis, ali samo kao slika, a sliku možete samo gledati.

Zato se tabla čuva kao skup strukturiranih objekata umjesto kao obična slika, a svaka linija, oblik i komad teksta zadržava svoja svojstva. Tablu je kasnije moguće ponovo učitati i nastaviti uređivati.

S Fabric.js-om razlika je jedan poziv metode:

1// a picture of the board: viewable, not editable2const image = canvas.toDataURL({ format: 'png' })3 4// the board itself: every object with its properties5const board = canvas.toJSON()6await api.put(`/meetings/${meetingId}/board`, board)7 8// next time, the same board, still editable9const saved = await api.get(`/meetings/${meetingId}/board`)10await canvas.loadFromJSON(saved)11canvas.requestRenderAll()

Na prvi pogled faktura i tabla idu u suprotnim smjerovima. Faktura se zamrzava kao renderovan dokument, a tabla ne.

Ipak, u oba slučaja pitanje je bilo čemu sačuvani zapis služi. Izdata faktura služi kao dokaz šta je izdato, pa sistem čuva tačno ono što je izdato i ništa to ne smije ponovo izračunati iz drugih podataka. Tabla služi da se rad nastavi, pa sistem čuva objekte s kojima se radi umjesto njihove slike. Kupon tome dodaje i vrijeme: zapis prvo postoji, a važi tek kasnije, i sistem mora znati u kojem je od ta dva stanja.

U sva tri proizvoda zapis je ostao čitav i nakon događaja koji ga obično uništi.

Kad god sistem proizvodi nešto na šta će se neko kasnije oslanjati, prije dizajniranja tabele pitam četiri stvari:

1. Može li se ono što zapis prikazuje promijeniti nakon što nastane? Ako se izvodi u trenutku čitanja iz bilo čega što se mijenja, recimo iz šablona, koda ili referentnih podataka, onda može, htjeli vi to ili ne.
2. Treba li? Faktura ne treba. Tabla treba ostati uređiva. Nijedan od ta dva odgovora nije default: svaki treba izabrati.
3. Može li zapis postojati prije nego što počne važiti? Ako može, to su dva stanja i svako mora biti posebno zapisano, umjesto jednog reda i optimistične pretpostavke.
4. Šta zapis prebacuje iz jednog stanja u drugo i može li iko vidjeti zapise koji su između? Ako stanje čekanja niko ne vidi, zapisi se u njemu gube, a da to niko ne sazna.

Na carinskom sistemu zamrzavanje izdatog dokumenta bilo je ispravno, ali nepotpuno, jer šablon nikad nismo verzionisali. Nijedna izdata faktura nije se mogla promijeniti, ali nije postojao zapis o tome koja ju je verzija šablona napravila, ni ko je i kada mijenjao šablon.

Snapshot je riješio hitno pitanje, a pitanje revizije ostavio otvorenim. Popravka je mala ako se uradi na početku: šabloni trebaju biti append-only, kao i izdati dokumenti, a svaki izdati dokument treba upućivati na verziju šablona iz koje je nastao.

1CREATE TABLE invoice_template_versions (2  id          bigserial PRIMARY KEY,3  body        text        NOT NULL,4  changed_by  text        NOT NULL,5  changed_at  timestamptz NOT NULL DEFAULT now()6);7 8ALTER TABLE issued_invoices9  ADD COLUMN template_version_id bigint10  REFERENCES invoice_template_versions (id);

Kad je dokument zamrznut, a šablon verzionisan, arhiva pokazuje i šta je izdato i zašto taj dokument izgleda baš tako.