Framework voor durable actors

Pipelines, workflows en AI-agents die nooit de draad kwijtraken.

Cicada is een framework om systemen te bouwen uit kleine, duurzame werkers: actors. Elke actor onthoudt zijn toestand en overleeft crashes en deploys. Zet ze bij elkaar en je krijgt CI/CD, agent-pipelines, planners en alerting, met niet meer dan een database.

issue #42 → pull requesteen AI-agentpipeline
✓Plan de wijziging09:08 · server-1
✓Schrijf de code09:11 · server-1
✕Draai de tests09:14 · server-1 viel uit
✓Draai de tests, opnieuw09:14 · server-2 nam het na 30 seconden over
✓Open de pull request09:16 · server-2
◷Wacht op review door een mens2 dagen · er wacht geen server
✓Gemerged. Sluit het issuedonderdag 11:02 · server-3
Resultaat: één pull request. Niemand hoefde iets te merken, te herstarten of te repareren.
1
Laag 1 · voor iedereen

Wat je kunt bouwen

Alles waarbij werk tijd kost, uit meerdere stappen bestaat of niet kwijt mag raken. Hier zijn zes systemen, uitgewerkt tot op het laatste bericht. Kies er een om de actors te zien.

meer ideeën

Met dezelfde onderdelen bouw je veel andere systemen.

Klant-onboarding
Documenten verzamelen, controleren, wachten op akkoord, na drie dagen herinneren.
Abonnementen
Op tijd verlengen, een mislukte betaling opnieuw proberen, uitstel geven en dan opschorten.
Reserveringen
Eén actor per kamer of stoel. Een optie verloopt via een timer. Dubbel boeken kan niet.
Integratiehub
Twee systemen pagina voor pagina synchroniseren, binnen hun limieten, en bewaren wat mislukte.
Onderzoeksagents
Een planner splitst een vraag, agents beantwoorden de delen parallel, een mens keurt het resultaat goed.
Gefaseerde uitrol
Uitrollen naar 1%, wachten, gezondheid controleren, door naar 10%. Terugdraaien bij een alarm.
Apparatenbeheer
Eén actor per apparaat: de laatst bekende toestand, de wachtende opdrachten en een stilte-alarm.
Ondertekenen
Vijf mensen vragen, wachten op allemaal of op de eerste weigering, de trage herinneren.
Mailcampagnes
Een tijdlijn per contact: mail, een week wachten, controleren, volgende mail. Afmelden annuleert de rest.
Live chat
Sessies die onbevestigde berichten bewaren en ze na opnieuw verbinden op volgorde afspelen.
ingebouwd, niet zelf gebouwd

Elk van deze systemen krijgt dit er gratis bij.

Een server herstart midden in een stap.
Een andere server voert die stap opnieuw uit. Wat al was opgeslagen, wordt niet nog een keer opgeslagen.
Een proces wacht dagen op een mens of een betaling.
Het wachten is een rij in de database. Het kost geen geheugen en overleeft elke deploy.
Er gebeuren twee dingen tegelijk met dezelfde order.
Elke actor verwerkt één bericht tegelijk. Per order is er één eigenaar, dus er is geen race.
Een extern systeem is traag of ligt eruit.
Berichten worden opnieuw geprobeerd volgens een beleid dat jij instelt. Wat blijft mislukken wordt bewaard, zodat je het kunt inzien en opnieuw kunt versturen.
Niemand weet waar een proces vastzit.
Je kunt elke actor en elk wachtend bericht bekijken, en ze pauzeren, opnieuw proberen of annuleren.
2
Laag 2 · voor architecten

Hoe de actors werken

Elk systeem hierboven is een handvol actors die elkaar berichten sturen. Deze laag laat zien wie ze zijn en wat er tussen hen beweegt.

Een actor is eigenaar van één ding

Hij heeft een naam, zoals order/1042, en een eigen opgeslagen toestand. Niemand anders wijzigt die toestand.

Actors praten via berichten

Een bericht wacht in het postvak van de actor waarvoor het bestemd is. Elke actor verwerkt één bericht tegelijk, op volgorde.

Een beslissing wordt in één stap opgeslagen

De nieuwe toestand en de berichten die hij verstuurt worden samen weggeschreven. Een timer is gewoon een bericht aan jezelf, voor later.

zes systemen, bericht voor bericht

Volg de berichten door een systeem.

Druk op afspelen, of klik op een stap. De namen zijn voorbeelden: jouw actors krijgen de namen van jouw bedrijf.

ingebouwde actors

Tien actors zijn kant-en-klaar.

Je schrijft geen planner of rate limiter. Ze worden met Cicada meegeleverd, het zijn gewone actors en ze hebben dezelfde garanties als je eigen actors. Kies er een om te zien hoe hij werkt.

van probleem naar ontwerp

Ontwerp je systeem samen met een agent.

Cicada wordt geleverd met een ontwerp-skill voor coding agents. Je vertelt een of twee verhalen uit je bedrijf, inclusief hoe ze misgaan. De skill stelt hooguit drie vragen tegelijk en schrijft het ontwerp in je repository, met diagrammen: welke actors er zijn, waar elke actor eigenaar van is, welke berichten ze sturen en wat er bij een time-out gebeurt.

Dezelfde skill beoordeelt een systeem dat al bestaat. Hij tekent de actors en berichten vanuit de code en meldt de zwakke plekken, elk met een spoor van hoe het misgaat.

  1. De belofteWat telt als succes? Wat mag nooit gebeuren?
  2. Wie en watWelke feiten gebeuren, en waardoor?
  3. Wie is eigenaar van elke regelWelke gegevens moet één beslissing samen zien?
  4. Identiteit en levensloopHoe heet elke actor? Wie maakt en beëindigt hem?
  5. VerantwoordelijkheidskaartenWat beslist elke actor, wat bezit hij en wat laat hij aan anderen?
  6. ProtocollenWelke berichten zijn er, en wat bewijst een antwoord?
  7. Coördinatie en tijdWat gebeurt er bij een time-out, een herhaling of een annulering?
  8. De buitenwereldWelke aanroepen verlaten het systeem, en wat als er een herhaald wordt?
  9. Controleren en vereenvoudigenKan een kort spoor een regel breken? Welke actors kunnen weg?
3
Laag 3 · voor engineers

Onder de motorkap

Wat er gebeurt als één actor één bericht verwerkt, wat Cicada garandeert, hoe het schaalt en hoe de code eruitziet in drie talen.

de beurt

Eén bericht, één transactie.

Een actor is een rij met toestand plus een postvak in je database. Het verwerken van één bericht heet een beurt. Elke beurt heeft dezelfde vier stappen.

1 claim

Claimen

Een node pakt het volgende bericht dat aan de beurt is en krijgt een tijdelijke lease op de actor.

2 run

Uitvoeren

Jouw handler leest de toestand en beslist. Alles wat hij wil wijzigen wordt gebufferd.

3 commit

Committen

Alles wordt samen weggeschreven, of helemaal niet.

nieuwe toestand + uitgaande berichten + nieuwe actors + uitkomst
4 sleep

Rusten

De actor verdwijnt uit het geheugen. Het is weer een rij, tot het volgende bericht aan de beurt is.

Waarom “Cicada”? Een cicade wacht jaren onder de grond en komt precies op tijd boven. Een Cicada-actor wacht in de database en wordt wakker als het volgende bericht aan de beurt is.

garanties

Zes garanties, elk gekoppeld aan tests.

G1

Serieel

Beurten van één actor overlappen nooit.

G2

Atomair

Toestand, berichten en uitkomst worden samen opgeslagen of helemaal niet.

G3

Eén uitkomst

Elk geaccepteerd bericht eindigt precies één keer. Niets raakt kwijt, niets wordt twee keer afgerond.

G4

Effecten één keer

Effecten binnen het systeem gebeuren precies één keer. Een handler draait alleen opnieuw als zijn beurt niet is opgeslagen.

G5

Volgorde

Berichten komen per actor op volgorde aan, en nooit te vroeg.

G6

Geen verborgen retry

Cicada voert een handler die klaar was nooit opnieuw uit. Retries volgen het beleid van het bericht.

Elke garantie staat naast de tests die haar bewijzen. Dezelfde conformance-suite draait op elke store: in het geheugen, SQLite en PostgreSQL. Een gerandomiseerde simulatie injecteert fouten zoals crashes, verloren antwoorden en verlopen leases, en controleert de garanties op de geschiedenis die dat oplevert.

Wat Cicada niet belooft

Aanroepen naar externe systemen, zoals een betaling of een e-mail, kunnen na een crash vaker dan één keer gebeuren. Elk bericht heeft een vast id dat je als idempotency key gebruikt, zodat het externe systeem de herhaling kan weigeren.

schalen

Begin met één bestand. Groei zonder herontwerp.

Dezelfde actorcode draait in alle drie de opstellingen. Je verandert hoe het wordt uitgerold, niet hoe het is geschreven.

nodeSQLite
1

Eén host

Eén binary en één SQLite-bestand. Genoeg voor een eerste product of een pilot, zonder iets anders te installeren.

nodenodenode
PostgreSQL
2

Veel nodes

Richt meer nodes op dezelfde PostgreSQL-database. Nodes zijn gelijk: er is geen leider, geen broker en geen clusterprotocol. Anderen nemen het werk over van een node die uitvalt.

TypeScriptKotlinRust
serverPG
3

Workers overal

Workers leasen beurten over HTTPS. Ze hebben geen databasegegevens nodig, kunnen in een ander netwerk draaien en kunnen in een andere taal geschreven zijn.

0geheugen voor een actor die wacht
16beurten tegelijk per node als standaard; je stelt het zelf in
30 slease, elke 10 s verlengd; zo snel wordt een dode node opgemerkt
15 minlangste beurt als standaard, per actortype aan te passen
  • Schaal één soort werk apart: start extra workers voor alleen dat actortype.
  • Pin een actor aan één node of worker als hij op een bepaalde machine moet draaien.
  • Uitrollen zonder werk te verliezen: een node stopt met claimen, maakt zijn beurten af en sluit dan.
  • Elk verwerkt bericht is één databasecommit. Cicada zet eenvoud en correctheid vóór pure snelheid.
talen

Eén actorsysteem, drie talen.

Rust
De kern: server, stores, command line en terminal-UI. Bouw het in je service in of draai het als binary.
TypeScript
Een worker voor Node.js. Actortypes definieer je met Zod-schema's.
Kotlin
Een worker voor de JVM, op coroutines. In preview.

Elk actortype publiceert een contract: de JSON-schema's van zijn toestand en berichten, plus een hash. De server bewaart één contract per type en weigert een worker met een afwijkend contract. Elke workerbibliotheek heeft hetzelfde versienummer als de Cicada-release waartegen ze is getest, samen met een Rust-server en een Rust-worker.

#[derive(Serialize, Deserialize, JsonSchema)]
#[serde(tag = "type")]
pub enum CounterMsg {
    Add { amount: i64 },
}

impl Actor for CounterActor {
    type Ref = Counter;
    type State = CounterState;

    async fn handle(&self, turn: &mut Turn<Self>, message: CounterMsg)
        -> HandlerResult
    {
        match message {
            CounterMsg::Add { amount } => turn.state_mut().total += amount,
        }
        Ok(())
    }
}
Dezelfde counter-actor. Alle drie kunnen tegelijk tegen één server draaien.

Een flow is een lang proces, geschreven als gewone code

Elke stap wordt opgeslagen zodra hij klaar is. Een opgeslagen stap draait nooit opnieuw.

flow onboarding.rsRust
let account_id: String = step.run("create-account", |key| async move {
    Ok(services.create_account(email, &key).await?)
}).await?;

step.run("send-welcome", |key| async move {
    Ok(services.send_welcome(email, &key).await?)
}).await?;

step.sleep("cool-off", Duration::from_secs(60)).await?;
journal onboarding/n1opgeslagen voortgang
✓ create-account   acc-f3f5ac1e
✓ send-welcome
◷ cool-off         due in 60 s
De slaap is een opgeslagen bericht. Er wacht geen proces.
beheer

Zie elke actor, elk postvak en elke uitkomst.

cicada tuide terminal-UI, op een gepauzeerde actor met drie wachtende berichten
Cicada terminal UI showing the actor sync/acme, its state as JSON and three pending messages in its mailbox
  • Terminal-UI en command line: inzien, pauzeren, hervatten, opnieuw proberen, annuleren, nu afleveren, legen.
  • HTTP-API met een gegenereerd OpenAPI-schema. Je voegt je eigen authenticatie toe.
  • Traces en metrics via OpenTelemetry.
  • Een live stream van toestandswijzigingen, om dashboards op te bouwen.
  • Een readiness-probe en een geordende shutdown, gemaakt voor containerplatformen.
  • Skills voor coding agents bij elke release: één om Cicada-code te schrijven, één om een actorsysteem te ontwerpen of te beoordelen.
geschiktheid

Wanneer wel, en wanneer niet.

Past goed

  • Processen die minuten, dagen of maanden duren.
  • Werk dat niet kwijt mag raken of dubbel mag gebeuren.
  • Regels die één duidelijke eigenaar per klant, order of apparaat nodig hebben.
  • Teams die liever een PostgreSQL-database hebben dan een nieuw platform om te beheren.

Niet het juiste gereedschap

  • Eventstreams met heel hoog volume.
  • Verzoeken die geen databasecommit kunnen lijden.
  • Zware dataverwerking of analytics.
  • Een probleem dat één functie of één tabel al oplost.
status

Cicada is nog niet openbaar.

Het framework is volop in ontwikkeling bij Helico en is nog niet als openbare bibliotheek uitgebracht. Heb je een pipeline, een workflow of een agent die geen werk mag verliezen? Vertel het ons, dan schetsen we samen de actors.

Contact
cicada.helico.app