Clepit

Enamik vormindatud teksti jõuab andmebaasi ühe HTML-plokina. See sobib seni, kuni sa ei taha sellega midagi muud teha kui seda uuesti näidata: leida iga lehte, kus mainitakse mõnda klienti, kuvada sama dokumenti veebilehel, e-kirjas ja mobiilirakenduses või lasta kahel inimesel seda korraga muuta nii, et kumbki ei kaotaks lõiku. Selleks ajaks on sõnad ja nende vormindus omavahel sassis ning ainus, mis dokumenti kindlalt lugeda oskab, on redaktor, mis selle kirjutas.

Clepit hoiab need kaks lahus. Leht on plokkide loend, iga plokk väike tüübitud objekt, ja dokument ise on JSON: pole märgendust, mida parsida, ega redaktorit, mida lugemiseks vaja läheks. Just seetõttu seisab redaktor ka omaette. @clepit/core on npm-is avaldatud MIT-litsentsi all ega tea majutatud poolest midagi, samas kui tööruum aadressil app.clepit.com on see, mille needsamad dokumendid saavad, kui neile antakse kaastöölised, õigused, ajalugu ja aadress avalikus veebis.

Leht on plokkide loend

Plokk koosneb neljast väljast: id, tüüp, andmed, mille see tüüp määrab, ja plokile rakendatud seaded. Lõigu andmetel on teistsugune kuju kui tabeli omadel, ja just tüüp ütleb, millist kuju oodata, nii et salvestatud dokumenti saab kontrollida, mitte üksnes parsida. Terve leht on ajatempel, versioon ja plokid järjekorras, mis on piisavalt väike, et seda oma silmaga lugeda ja pull request’is üle vaadata. Miski selles ei kirjelda, milline leht välja peaks nägema: see kuulub sellele, kes teda joonistab, ja just tänu sellele saab ühest dokumendist veebileht, e-kiri ja mobiiliekraan ilma et sellest kolm koopiat eksisteeriks.

Dokumendi joonistamine ilma brauserita

Renderdaja ei kirjuta kunagi otse brauserisse. Ta joonistab läbi õhukese kihi, mille taga on kaks tuge: üks ehitab päris lehesõlmi, teine ehitab sõne, ja sama plokikood töötab mõlemal. Nii joonistatakse avaldatud leht serveris, kus brauserit polegi, ja seetõttu on see, mida server toodab, seesama dokument, mille redaktor oleks näidanud, mitte teine teostus, mis tasapisi kõrvale kaldub. Sõnetugi võtab puhastaja kohustusliku argumendina ja tal pole meelega vaikeväärtust: paketi harilik puhastaja ehitab parsimiseks lehe, nii et seal ta töötada ei saa, ning vaikne taandumine märgivarjestusele riisuks iga dokumendi seest vormingu, sellest sõnagi lausumata. Nii jäetakse lünk nähtavale sinna, kus seda kasutatakse, selle asemel et see vaikeväärtuse sisse peita.

Lugemine ei maksa lugejale ühtegi JavaScripti

Reacti adapter tarnib oma kaks poolt eraldi, sest nad tahavad vastupidiseid asju. Sisukomponent töötab serveris ja väljastab valmis märgenduse juba lehe ehitamise ajal, nii et lugeja saab dokumendi kätte esimeses vastuses. Redaktorikomponent on ainult kliendipoolne, sest tema hoolitseb redaktori elutsükli eest ja enne brauseri olemasolu pole seal midagi hoida. Clepiti dokumendi lugemiseks ei lähe seega JavaScripti üldse tarvis. Kirjutamise juures jõuab kohale ka käitusaeg.

Mida leht mahutab

Paketiga tuleb kaasa kakskümmend kuus plokiliiki. Enamik on need, mida iga redaktor vajab: pealkirjad, lõigud, loendid, kontroll-loendid, tsitaadid, kood, tabelid, pildid, heli, video, failid, esiletõsted ja eraldajad. Ülejäänud on olemas sellepärast, et dokumentatsiooni kirjutamine küsib asju, mida kirjutamisvahend tavaliselt eirab. Sisukord, mis ehitab end ise dokumendi pealkirjadest ja lingib igaühele. Kokkuvolditavad osad ja veerud. Kaart, mis seisab teise lehe eest. Vabakäejoonistus. Ja tegevusplokk, mis salvestab, millist dokumenti jälgida, mitte koopiat selle tegevusest, nii et see näitab edasi toimuvat, selle asemel et tarduda sisestamise päeva. Vormindus ploki sees katab tavalised märgid, rasvane, kaldkiri, allajoonitud, läbi kriipsutatud, koodijupp, esiletõste ja lingid, ning lisaks kohtspikrid, olekusildid ja mainimised. Paketil endal pole ühtegi käitusaegset sõltuvust.

Valemid ja skeemid, joonistatud paketis endas

Kaks neist plokkidest kuvavad LaTeXi ja Mermaidi ning mõlemad teevad kogu töö paketis: parsivad lähtekoodi, arvutavad paigutuse, joonistavad tulemuse. Nende all pole ühtegi joonistusteeki ega pöördumist teenuse poole, et valemist või vooskeemist pilt teha. See on pigem sõnetoe tagajärg kui eelistus sõltuvuste osas. Plokk, mis sirutaks käe millegi järele, mida pakub ainult brauser, või võrgu järele, ei saaks joonistuda serveris, mis avaldatud lehti teenindab, ja siis näeks üks ja sama leht välja erinev sõltuvalt sellest, kes seda küsis.

API-teatmik, mis elab lehe sees

Anna OpenAPI plokile spetsifikatsioon, kleebituna või aadressiga viidatuna, ja ta joonistab selle, mida spetsifikatsioon kirjeldab: operatsioonid, nende teed ja parameetrid, päringu ja vastuse skeemid ning autentimisviisi. Iga operatsiooni jaoks koostab ta ka päringunäite cURL-is, TypeScriptis, Dartis ja Pythonis, mis on genereeritud spetsifikatsioonist, mitte trükitud autori poolt, kes uuendamise ära unustab. Manustusplokk vaatab välismaailma sama pilguga: ta tunneb ära peotäie teenuseid, mida ta tõesti kuvada suudab, kohtleb kõige muu puhul lihtsat linki korraliku tulemuse, mitte ebaõnnestumisena, ja keeldub otsesõnu joonistamast aadressi, mida ta ei usalda.

Kaks inimest samas lõigus

Reaalajas muudetavat lehte hoiab serveris üksainus ülesanne, üks lehe kohta, ja iga muudatus läbib selle järjekorras. Just see teeb üheaegse muutmise arusaadavaks: pole teist kirjutajat, kes esimesega võidu jookseks. Dokument ise on CRDT, nii et kaks inimest, kes samas lõigus kirjutavad, sulanduvad üksteise asemel kokku, ja maha jäänud klient jõuab järele, vahetades seda, mis kummalgi poolel puudu on. Iga muudatus lisatakse ettekirjutuslogisse enne, kui see kellelegi edastatakse, nii et see, mida teised dokumendis viibijad näevad, on juba püsivalt talletatud, mitte lihtsalt edasi antud. Õigusi jõustatakse serveris, mitte liideses: kaaslane, kes liitub ilma muutmisõiguseta, alandatakse lugemisele, ja seanss kontrollib seda õigust dokumendi lahtioleku ajal korrapäraselt üle, nii et ära võetud ligipääs tabab kedagi, kes juba kirjutab, selle asemel et oodata lehe uuesti laadimist.

Iga kirjutamine käib läbi ühe ukse

Dokumenti võib muuta inimene, kes sinna kirjutab, ja programm, mis kutsub API-t, ning need kaks teed said varem samale lehele kirjutada teineteisest sõltumatult. Enam ei saa. API kirjutus suunatakse samasse seanssi, mis hoiab elavat dokumenti, kus see rakendatakse ühe tehinguna kõrvuti käimasolevate muudatustega, nii et sündmustel on üksainus järjekord, mitte kaks kirjutajat eri arvamusega selle kohta, mida leht ütleb. Plokkide id-d säilitatakse dokumendi tagasikirjutamisel, sest kommentaarid on nende külge ankurdatud ja uusi id-sid loov ühildamine jätaks iga kommentaari osutama eimiskile. Ja kui saadud plokkide hulk on täpselt sama, mis juba salvestatud, ei kirjutata üldse midagi.

Ainus kanal, kuhu masinavõti ei ulatu

Isiklik API-võti töötab REST-i, GraphQL-i, GraphQL-i tellimussokli ja MCP puhul. Koostöösokli puhul see ei tööta, ja see on tahtlik. Iga koostöös tehtud muudatus templiga märgistatakse selle inimesega, kes selle tegi, ning need templid saavad lehe ajaloos kirja pandud autorluseks. Masinprintsipaal, kes seal muudaks, kirjutaks autori, keda ükski inimene ei kirjutanud, ja selle hilisem tagasivõtmine tähendab ajaloo ümberkirjutamist, mitte rea kustutamist. Piir ei jookse veebisoklite ja HTTP vahel: küsimus on selles, kas kanal kirjutab autoriga ajalugu. Reeglit jõustab koodi kuju, mitte mälu, sest võtme vastuvõtmine nõuab teadlikku üleminekut teisele autentimiskutsele, ja kui mõni kanal seda teeb, kukub test läbi.

Tööruum omaenda aadressil

Iga tööruum on rentnik, kellel on oma alamdomeen alates loomise hetkest, ja rentnik tuletatakse aadressist, millele päring saabus. See, millises rentnikus sa oled, on seega otsustatud enne, kui sinu andmetest midagi loetakse, mitte hiljem lisatud filtriga, mille keegi võib unustada. Selle all jõustab piiri andmebaas ise reataseme turvalisusega: iga päring võtab ühenduse, templiga märgib sellele kutsuja identiteedi, ja kogum pühib selle oleku ühenduse tagastamisel, nii et ühe päringu identiteet ei saa lekkida järgmise päringu päringutesse.

Domeeni nõudmine pole sama mis selle tõestamine

Ettevõtte paketiga tööruum saab oma lehti serveerida omaenda domeenilt. Domeeni nõudmine ja sealt serveerimine on meelega eraldi sammud: domeen salvestatakse kinnitamata kujul ja lahendaja eirab seda täielikult, kuni DNS-i ilmub kinnitav kirje. Igaüks võib vormi trükkida mõne teise firma aadressi. Ainult see, kes seda domeeni valitseb, saab avaldada kirje, mis selle elavaks teeb.

Iga versioon, mis lehel on olnud

Clepit hoiab versioone, mitte üht praegust olekut. Hetktõmmis tehakse automaatselt, samal ajal kui inimesed töötavad, ja seda piiratakse nii, et harilik kirjutamine ei tekitaks neid sadu: uus kirjutatakse siis, kui on möödunud kümme minutit või muutunud kümme plokki, kumb enne juhtub. Taastamine on üksainus tehing: vana hetktõmmis rakendatakse, plokid ühildatakse ja taastamine ise kirjutatakse uue versioonina, nii et tagasiminek jääb kirja, mitte ei kaoks vaikselt. Ühildamine hoiab meelega alles lähtekoha plokkide id-d, sest kommentaarid on ankurdatud plokkide külge ja lehe taastamine uute id-dega jätaks iga selle kommentaari ankruta.

Selle uuesti ülesleidmine

Otsing käib lehtede projektsiooni peal ja päring läheb läbi Postgresi enda veebiotsingu parseri, mitte ei panda käsitsi SQL-iks kokku, nii et inimene võib trükkida jutumärke ja miinusmärke ega teki sellest mingit süstimispinda. Jagatud tööruumis loeb aga see, kus paikneb õiguste kontroll. Otsing ühendab lehtede tabeli, ja selle tabeli reataseme turvalisus kehtib ka ühenduse kohta, nii et tulemused on juba piiratud nende lehtedega, mida küsija näha tohib. Filtrid (lehepuu alamosa, kes viimati muutis, millal viimati redigeeriti) laotakse sellele peale lisatingimustena. Iga neist kitsendab; ükski neist ei saa laiendada, sest kõik asuvad sama kontrolli taga.

Avaldamine külmutab, jagamine mitte

Need on kaks eri asja ja Clepit kohtleb neid meelega erinevalt. Lehe avaldamine külmutab praeguse dokumendi versioonina, suunab lehe sellele ja teeb selle avalikuks: see, mida külastaja loeb aadressil clepit.space, näiteks kujul acme.clepit.space/handbook, on seesama külmutatud versioon, mitte pärast tehtud muudatused. Avaldamise tühistamine kustutab need viidad, kuid jätab avaliku aadressi alles, nii et hiljem uuesti avaldades jõuab sama aadressi juurde, selle asemel et katkestada iga sellele osutanud link. Jagamislink on vastupidine: see serveerib elavat dokumenti, nii et saaja nähtu muutub koos lehega.

Link, mille saad tagasi võtta

Jagamislink on märk, mille saad tühistada, ja loomisel võib sellele anda aegumise. Salvestatakse ainult märgi räsi, nii et link näidatakse loomise hetkel üks kord ega ole pärast seda andmebaasist taastatav, ei meie ega kellegi teise poolt, kes selleni jõuab. Need lingid annavad lugemise, mitte kommenteerimise: kommentaar vajab autorit, ja lingi hoidja ei ole autor.

Sisselogimine omaenda kataloogist

Tööruum võib anda autentimise üle omaenda identiteedipakkujale: OpenID Connect äripaketiga, SAML ettevõtte paketiga, ja kõrval SCIM kataloogi sünkroonimiseks. SCIM katab kasutajaressursi, mida Okta ja Entra päriselt juhivad, ning teeb standardi ilmsest lugemisest ühe teadliku kõrvalekalde: kustutamine deaktiveerib liikme, mitte ei kustuta teda. Spetsifikatsioon lubab seda, ja alternatiiv on kataloogisünk, mis suudab hävitada tööruumi sisu sellega, et keegi eemaldatakse mõnest rühmast.

Neli viisi sellega rääkida

REST katab nelikümmend neli operatsiooni /v1 all, mida kirjeldab OpenAPI dokument, mis genereeritakse marsruutidest endist, mitte ei kirjutata nende kõrvale, ja pidev integratsioon võrdleb seda väljundit hoidlasse pandud koopiaga, nii et registrist mööda hiiliv marsruudimuudatus ei saa vaikselt sisse lipsata. GraphQL katab rakenduse mudeli ja kannab tellimusi omaenda sokli kaudu. Reaalaeg on eraldi protsess, mistõttu lüüsi taaskäivitamine ei vii päringupinda endaga kaasa, ja see annab loa sokli, mitte toa kaupa: iga sündmuse puhul hinnatakse kõiki rentniku ühendusi ühe koondatud kontrolliga ja saavad ainult need, kellel on lubatud seda näha. MCP avab needsamad operatsioonid tehisintellekti agentidele tööriistadena, ja ükski tööriist ei usalda kutsujalt tulnud id-d otsustamaks, millises tööruumis ta tegutseb; kirjutamised käivad läbi samade teenuste, mida kasutab liides, nii et õiguste kontrollid ja jälgimislogi on needsamad.

Kellele see on

Meeskondadele, kes vajavad redaktorit, mille üle neil on kontroll, ja arendajatele, kes põimivad struktureeritud sisu oma tootesse.

Külasta Clepit: clepit.com