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.
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.
AI-agentpipeline
Een issue erin, een gereviewde pull request eruit. Met pauzeren, hervatten en een mens aan het stuur. Onze eigen code factory werkt zo.
Git-hosting met CI/CD
Repository's, merge requests, pipelines, runners en deploys. Een kleine GitLab, gebouwd uit vijf soorten actors.
Orderworkflow
Voorraad reserveren, betaling innen, verzenden. De voorraad teruggeven als de betaling uitblijft.
Geplande jobs
Nachtelijke jobs die opnieuw proberen, het team informeren en alarm slaan als ze helemaal niet gedraaid hebben.
Alerts en piketdienst
Merken dat iets stilvalt, één incident openen en escaleren tot een mens reageert.
Notificatiehub
Eén event bereikt de juiste mensen: meteen in Slack, of in één dagelijkse mail voor wie dat liever heeft.
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.
Elk van deze systemen krijgt dit er gratis bij.
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.
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.
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.
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.
- De belofteWat telt als succes? Wat mag nooit gebeuren?
- Wie en watWelke feiten gebeuren, en waardoor?
- Wie is eigenaar van elke regelWelke gegevens moet één beslissing samen zien?
- Identiteit en levensloopHoe heet elke actor? Wie maakt en beëindigt hem?
- VerantwoordelijkheidskaartenWat beslist elke actor, wat bezit hij en wat laat hij aan anderen?
- ProtocollenWelke berichten zijn er, en wat bewijst een antwoord?
- Coördinatie en tijdWat gebeurt er bij een time-out, een herhaling of een annulering?
- De buitenwereldWelke aanroepen verlaten het systeem, en wat als er een herhaald wordt?
- Controleren en vereenvoudigenKan een kort spoor een regel breken? Welke actors kunnen weg?
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.
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.
Claimen
Een node pakt het volgende bericht dat aan de beurt is en krijgt een tijdelijke lease op de actor.
Uitvoeren
Jouw handler leest de toestand en beslist. Alles wat hij wil wijzigen wordt gebufferd.
Committen
Alles wordt samen weggeschreven, of helemaal niet.
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.
Zes garanties, elk gekoppeld aan tests.
Serieel
Beurten van één actor overlappen nooit.
Atomair
Toestand, berichten en uitkomst worden samen opgeslagen of helemaal niet.
Eén uitkomst
Elk geaccepteerd bericht eindigt precies één keer. Niets raakt kwijt, niets wordt twee keer afgerond.
Effecten één keer
Effecten binnen het systeem gebeuren precies één keer. Een handler draait alleen opnieuw als zijn beurt niet is opgeslagen.
Volgorde
Berichten komen per actor op volgorde aan, en nooit te vroeg.
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.
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.
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.
Eén host
Eén binary en één SQLite-bestand. Genoeg voor een eerste product of een pilot, zonder iets anders te installeren.
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.
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.
- 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.
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(()) } }
const Counter = actorType({ type: "counter", state: z.object({ total: z.int() }), messages: { Add: z.object({ amount: z.int() }), }, handle(turn, message) { switch (message.type) { case "Add": turn.state = { total: turn.state.total + message.amount }; return; } }, }); const source = new HttpTurnSource("https://actors.internal"); await new Worker(source, [Counter]).start();
@Serializable sealed interface CounterMsg { @Serializable @SerialName("Add") data class Add(val amount: Long) : CounterMsg } @Serializable @SerialName("CounterState") data class CounterState(val total: Long = 0) val Counter = actorType<CounterState, CounterMsg>("counter") { handle { msg -> when (msg) { is CounterMsg.Add -> state = state.copy(total = state.total + msg.amount) } } }
Een flow is een lang proces, geschreven als gewone code
Elke stap wordt opgeslagen zodra hij klaar is. Een opgeslagen stap draait nooit opnieuw.
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?;
✓ create-account acc-f3f5ac1e ✓ send-welcome ◷ cool-off due in 60 s
Zie elke actor, elk postvak en elke uitkomst.
- 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.
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.
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.