40 El Llibre de Ridgun

La lib `net_agent` — Supervisor de Connexions de Xarxa i Pont d'Esdeveniments No Bloquejant

40.1. Per què existeix la lib `net_agent`? (El problema real i la filosofia Ridgun)

«Per què necessito una lib net_agent escrita des de zero en Ridgun pur en lloc d'enllaçar una llibreria de C de tota la vida?»

Aquesta és la primera pregunta que es fa qualsevol enginyer de sistemes en arribar a net_agent. I la resposta resumeix tota la filosofia de ridgun-libs:

Siguem sincers: en un servidor real com Solstice, acceptar connexions TCP és la part fàcil; el difícil és limitar el màxim de clients simultanis, desconnectar clients zombis inactius (idle timeout) i connectar el bucle ppoll amb els teus actors sense fuites de descriptors.

La lib net_agent tanca el cercle de ridgun-libs unint posix, socket i agent: gestiona taules de connexions supervisades (NetSupervisor), aplica límits de concurrència (max_conns), purga connexions inactives (net evict idle) i converteix esdeveniments de descriptors del nucli en esdeveniments tipats (NetEvReadyRead, NetEvReadyWrite, NetEvTimeout, NetEvError) a més d'oferir un pas d'eco TCP complet d'extrem a extrem (net tcp echo step).

En un ecosistema tradicional, resoldre les tasques del domini AGENT implica arrossegar dependències externes en C, lluitar amb punters crus, conversions opaques de tipus, excepcions no verificades o pauses impredictibles del recol·lector de brossa. En Ridgun, la lib net_agent (src/main/ridgun/lib/net_agent.rg) aborda el problema amb quatre principis innegociables:

Declara import net_agent (o import net_agent as alias) a l'inici del fitxer: cada lib defineix el seu espai de noms module :: net agent i en mode --strict les funcions multi-paraula s'invoquen sempre amb espais naturals.
Encadena les teves canonades d'esquerra a dreta amb ->: escriu entrada pas u -> pas dos -> resultat, fes servir màscares (+ _ _ +) per desestructurar seqüències i omet _ = en sentències seqüencials (o descarta amb -> ()).
Recursió de cua amb TCO (Tail-Call Optimization): tots els recorreguts interns de net_agent es compilen a bucles natius en espai de pila $O(1)$.
Memòria determinista (RMM1 / RMM2): cada estructura intermèdia s'allibera en l'instant exacte en què acaba la seva última lectura, sense Garbage Collector.

40.2. Artefactes natius, importació i catàleg complet de l'API de `net_agent`

A ridgun-libs, net_agent és una lib de primera classe situada a src/main/ridgun/lib/net_agent.rg (domini AGENT). En compilar amb stable bundle, s'empaqueta en tres formats natius:

Artefacte	Ruta	Propòsit
Bundle Ridgun	`target/bundles/net_agent.rglib`	Distribució i importació directa amb `import net_agent`
Fitxer compilat	`target/net_agent.rgc`	Artefacte intermedi verificat per `ridgunc`
Objecte compartit ELF64	`target/libnet_agent.so`	Biblioteca dinàmica nativa sense dependències de C ni `libc`

Cada lib declara el seu propi espai de noms amb module :: net agent: n'hi ha prou d'escriure import net_agent (o import net_agent as alias) a la capçalera i cridar les seves funcions amb espais naturals (la meva funcio x) i canonades -> (x la meva funcio -> resultat).

40.2.1. Resum de famílies funcionals de `net_agent`

Signatura / Funció / Tipus	Què fa i quan fer-la servir
`net supervisor new : Int -> Int -> NetSupervisor`	Crea un supervisor de connexions amb límit `max_conns` i inactivitat `idle_timeout_ms`
`net register conn / net record rx / net record tx / net close conn`	Registra sockets acceptats, actualitza comptadors de bytes/activitat i tanca parells
`net evict idle : NetSupervisor -> Int -> (NetSupervisor, [Int])`	Tanca i expulsa connexions inactives més enllà d'`idle_timeout_ms`, retornant els seus FDs
`net poll fd : Int -> Bool -> Int -> NetEvent`	Pont `wait fd` no bloquejant que emet `NetEvReadyRead`, `NetEvReadyWrite`, `NetEvTimeout` o `NetEvError`
`net tcp echo step : String -> Int -> (Int, String)`	Pas complet d'extrem a extrem TCP loopback (`listen/connect/accept/supervise/echo`)

40.2.2. Catàleg exhaustiu de tipus i signatures a `src/main/ridgun/lib/net_agent.rg`

A continuació tens l'inventari complet de tipus algebraics (type), operadors (op ::) i signatures de funcions (fn ::) definits a src/main/ridgun/lib/net_agent.rg (2 tipus, 0 operadors i 8 funcions):

Tipus algebraics i registres (type) de net_agent:

type ConnSlot = ConnSlot Int Agent
type StepOutcome = ConnKeep ConnSlot String | ConnClosed

#	Funció / Signatura (`fn ::`)	Tipus de Retorn
`1`	`fn :: conn poll step ConnSlot`	`StepOutcome`
`2`	`fn :: conn handle event Int Agent Int`	`StepOutcome`
`3`	`fn :: conn feed payload Int Agent String`	`StepOutcome`
`4`	`fn :: conn cast str A`	`String`
`5`	`fn :: conn drain outbound Int Agent Option`	`StepOutcome`
`6`	`fn :: reactor sweep [ConnSlot]`	`[ConnSlot]`
`7`	`fn :: reactor sweep next StepOutcome [ConnSlot]`	`[ConnSlot]`
`8`	`fn :: reactor shutdown [ConnSlot]`	`()`

40.3. Explorant `net_agent` a fons: Exemples pas a pas de cada funcionalitat

No n'hi ha prou de veure la taula de signatures: explorarem cadascuna de les funcionalitats de la lib net_agent mitjançant exemples progressius i executables en Ridgun. Començarem per les dues receptes tabulars d'ús quotidià i després recorrerem en detall tots els escenaris funcionals, transformacions i casos límit verificats a src/test/ridgun/test net_agent.rg.

40.3.1. Exemple 1: Flux principal en estil tabular amb `net_agent`

Observa com en Ridgun els signes = i els passos de transformació amb net_agent queden alineats com una taula neta, sense variables mutables innecessàries ni efectes laterals ocults:

import net_agent

fn :: barrer conexiones activas [ConnSlot] => [ConnSlot]
      barrer conexiones activas tabla =
        tabla reactor sweep

40.3.2. Exemple 2: Composició segura i gestió de casos de vora

Tota funció de la lib net_agent està dissenyada per compondre's amb guardes booleanes | i amb la resta de les 32 libs de ridgun-libs:

import net_agent

fn :: apagar reactor [ConnSlot] => ()
      apagar reactor tabla =
        tabla reactor shutdown

40.3.3. Exemple 3: Combinadors d'actors (`agent ask`, `try ask`, `send batch`, `map batch`, `drain ready`), pools particionats i reactor de connexions

En aquest exemple pràctic explorem de manera exhaustiva com es comporta net_agent en aquest bloc funcional, incloent-hi entrades estàndard, combinacions de paràmetres i valors frontera:

fn :: test spec combinators pool and net agent => ()
      test spec combinators pool and net agent =
        w1 = agent (ag double worker)
        assert int equals (agent ask w1 21) 42 "agent ask 21 -> 42"
        mb = agent map batch w1 [3, 5, 7]
        assert int equals (ag sum ints mb) 30 "agent map batch [3,5,7] -> [6,10,14] sum 30"
        agent send batch w1 [10, 20] -> ()
        rc = agent receive count w1 2
        assert int equals (ag sum ints rc) 60 "agent send batch + agent receive count -> 60"
        c_dr = new counter agent 100
        send 5 to c_dr
        send 10 to c_dr
        dr = agent drain ready c_dr
        assert int equals (ag sum ints dr) 220 "agent drain ready [105, 115] -> 220"
        agent stop all [w1, c_dr] -> ()
        assert false (is agent alive w1) "w1 stopped by agent stop all"
        assert false (is agent alive c_dr) "c_dr stopped by agent stop all"

        s0 = new counter agent 0
        s1 = new counter agent 1000
        pl = Pool 2 [s0, s1]
        assert int equals (pool size pl) 2 "pool size 2"
        assert int equals (pool ask shard pl 0 5) 5 "pool ask shard 0 -> 5"
        assert int equals (pool ask shard pl 1 7) 1007 "pool ask shard 1 -> 1007"
        assert int equals (pool ask shard pl (0 - 3) 3) 1010 "pool ask shard negative key -> shard 1"
        pool broadcast pl 10 -> ()
        all_dr = pool drain all pl
        assert int equals (ag sum ints all_dr) 1035 "pool drain all [15, 1020] -> 1035"
        pool shutdown pl -> ()
        assert false (is agent alive s0) "pool s0 stopped"
        assert false (is agent alive s1) "pool s1 stopped"

        ca = agent (ag echo conn step) (CounterState 0)
        cb = agent (ag echo conn step) (CounterState 0)
        s_eof = conn feed payload (0 - 1) ca ""
        s_err = conn handle event (0 - 1) cb 8
        kept  = reactor sweep next s_eof (reactor sweep next s_err [])
        assert int equals (agent list len kept 0) 0 "reactor sweep next prunes closed slots"
        assert false (is agent alive ca) "ca stopped on EOF"
        assert false (is agent alive cb) "cb stopped on POLLERR"
        cc = agent (ag echo conn step) (CounterState 0)
        reactor shutdown [ConnSlot (0 - 1) cc] -> ()
        assert false (is agent alive cc) "cc stopped on reactor shutdown"

40.3.4. Exemple 4: Cicle de vida d'agents (`is agent alive`, `agent status`, `stop agent`) i agent comptador amb estat aïllat (`new counter agent`)

En aquest exemple pràctic explorem de manera exhaustiva com es comporta net_agent en aquest bloc funcional, incloent-hi entrades estàndard, combinacions de paràmetres i valors frontera:

fn :: test agent lifecycle and counter => ()
      test agent lifecycle and counter =
        assert str eq (format agent status AgentRunning) "running" "format AgentRunning"
        assert str eq (format agent status AgentStopped) "stopped" "format AgentStopped"
        assert str eq (format agent status (AgentTimedOut 250)) "timeout after 250 ms" "format AgentTimedOut"
        assert str eq (format agent status (AgentFailed "boom")) "failed: boom" "format AgentFailed"
        assert str eq (format agent reply (ReplyInt 42)) "42" "format ReplyInt"
        assert str eq (format agent reply (ReplyStr "ok")) "ok" "format ReplyStr"
        assert str eq (format agent reply (ReplyBool True)) "true" "format ReplyBool True"
        assert str eq (format agent reply (ReplyBool False)) "false" "format ReplyBool False"
        assert str eq (format agent reply ReplyEmpty) "agent outbox empty" "format ReplyEmpty"
        assert str eq (format agent reply ReplyStopped) "agent stopped" "format ReplyStopped"
        assert str eq (format agent reply (ReplyTimeout 50)) "agent timeout after 50 ms" "format ReplyTimeout"
        assert str eq (format agent reply (ReplyError "bad")) "agent error: bad" "format ReplyError"

        c   = new counter agent 10
        assert ok (is agent alive c)
        assert str eq (format agent status (agent status c)) "running" "counter running"
        assert str eq (format agent reply (try poll int c)) "agent outbox empty" "empty outbox before send"
        assert eq (counter get c) 10
        assert eq (counter add c 5) 15
        assert eq (counter add c 7) 22
        assert str eq (format agent reply (ask int c 8)) "30" "ask int 8 -> 30"
        assert str eq (format agent reply (ask int with timeout c 12 200)) "42" "ask int with timeout -> 42"
        assert eq (counter reset c) 0
        assert eq (counter get c) 0
        bs  = ask batch int c [1, 2, 3, 4]
        assert eq (ag sum ints bs) 20

        c2  = new counter agent 100
        rel = relay int c c2 5
        assert str eq (format agent reply rel) "115" "relay int c (10+5=15) -> c2 (100+15=115)"

        st1 = stop agent c
        assert str eq (format agent status st1) "stopped" "stop agent returns AgentStopped"
        assert eq (is agent alive c) False
        assert str eq (format agent status (agent status c)) "stopped" "agent status after stop"
        assert str eq (format agent reply (ask int c 1)) "agent stopped" "ask int after stop"
        assert str eq (format agent reply (try poll int c)) "agent stopped" "try poll int after stop"
        assert str eq (format agent reply (ask int with timeout c 1 50)) "agent stopped" "ask int with timeout after stop"
        assert str eq (format agent reply (relay int c c2 1)) "agent stopped" "relay int after stop"
        c0  = new counter agent 0
        assert int equals (counter get c0) 0 "counter 0 initial"
        assert int equals (counter add c0 3) 3 "counter 0 add 3"
        stop agent c0
        stop agent c2
        assert eq (is agent alive c2) False

40.3.5. Exemple 5: Agent de bitàcola append-only (`new log agent`) i magatzem clau-valor en memòria per pas de missatges (`new kv agent`)

En aquest exemple pràctic explorem de manera exhaustiva com es comporta net_agent en aquest bloc funcional, incloent-hi entrades estàndard, combinacions de paràmetres i valors frontera:

fn :: test log and kv agents => ()
      test log and kv agents =
        lg  = new log agent "\n"
        assert ok (is agent alive lg)
        assert str eq (format agent reply (try poll str lg)) "agent outbox empty" "log empty outbox"
        assert str eq (log read lg) "" "initial log empty"
        assert str eq (log append lg "alpha") "alpha" "log append alpha"
        assert str eq (log append lg "beta") "alpha\nbeta" "log append beta"
        assert str eq (format agent reply (ask str with timeout lg "gamma" 200)) "alpha\nbeta\ngamma" "ask str with timeout gamma"
        assert str eq (log read lg) "alpha\nbeta\ngamma" "log read"
        assert str eq (log clear lg) "" "log clear"
        assert str eq (log read lg) "" "log read after clear"
        b   = ask batch str lg ["one", "two"]
        assert str eq (ag join strs b) "one|one\ntwo" "ask batch str"
        lg2 = new log agent ":"
        assert str eq (format agent reply (relay str lg lg2 "three")) "one\ntwo\nthree" "relay str"
        stop agent lg
        stop agent lg2
        assert str eq (format agent reply (ask str lg "x")) "agent stopped" "ask str after stop"

        kv  = new kv agent
        assert ok (is agent alive kv)
        assert int equals (kv count kv) 0 "kv count 0"
        assert false (kv has kv "host") "kv has host false"
        assert str eq (kv put kv "host" "127.0.0.1") "127.0.0.1" "kv put host"
        assert str eq (kv put kv "port" "8080") "8080" "kv put port"
        assert int equals (kv count kv) 2 "kv count 2"
        assert ok (kv has kv "host")
        assert ok (kv has kv "port")
        assert str eq (kv get kv "host") "127.0.0.1" "kv get host"
        assert str eq (kv get kv "port") "8080" "kv get port"
        assert str eq (kv keys kv) "host,port" "kv keys"
        assert str eq (kv put kv "port" "9090") "9090" "kv overwrite port"
        assert str eq (kv get kv "port") "9090" "kv get updated port"
        assert int equals (kv count kv) 2 "kv count after overwrite"
        assert str eq (kv delete kv "host") "127.0.0.1" "kv delete host"
        assert false (kv has kv "host") "kv has host after delete"
        assert int equals (kv count kv) 1 "kv count 1"
        assert str eq (kv clear kv) "" "kv clear"
        assert int equals (kv count kv) 0 "kv count after clear"
        stop agent kv
        assert false (is agent alive kv) "kv stopped"

40.3.6. Exemple 6: Sondeig no bloquejant de descriptors (`conn poll step`), escombrat de taula de connexions (`reactor sweep`) i apagada neta (`reactor shutdown`)

En aquest exemple pràctic explorem de manera exhaustiva com es comporta net_agent en aquest bloc funcional, incloent-hi entrades estàndard, combinacions de paràmetres i valors frontera:

import agent
import net_agent

fn :: sesion eco (n : Int) (trama : String) => (Int, String)
      sesion eco n trama =
        sig = n + 1
        (sig, "[#{sig}] {trama}")

fn :: ejemplo reactor conexiones (fd1 : Int) (fd2 : Int) => [ConnSlot]
      ejemplo reactor conexiones fd1 fd2 =
        ag1     = agent sesion eco 0
        ag2     = agent sesion eco 0
        activas = [ConnSlot fd1 ag1, ConnSlot fd2 ag2]
        -- Barrido no bloqueante (sys poll timeout=0) de todas las conexiones
        vivas   = reactor sweep activas
        -- Cierre ordenado de descriptores y parada determinista de agentes
        reactor shutdown vivas -> ()
        []

40.4. Sota el capó: com està construïda `net_agent` en Ridgun pur (`src/main/ridgun/lib/net_agent.rg`)

Un dels majors avantatges de ridgun-libs és que no hi ha caixes negres en C. Pots obrir src/main/ridgun/lib/net_agent.rg i llegir exactament com està implementada cada operació fent servir pattern matching, arbres de guardes | / |. i recursió de cua (TCO). Vegem les peces clau de la seva implementació real:

40.4.1. Implementació interna: Core Implementation Part 1

Fixa't en com net_agent.rg estructura les signatures fn :: ... => ... primer i resol cada cas mitjançant equacions alineades i crides de cua:

module :: net agent

type ConnSlot = ConnSlot Int Agent

type StepOutcome = ConnKeep ConnSlot String | ConnClosed

fn :: conn poll step ConnSlot         => StepOutcome
      conn poll step (ConnSlot fd ag) =
        sys poll fd 1 0 -> ev
        conn handle event fd ag ev

fn :: conn handle event Int Agent Int => StepOutcome
      conn handle event fd ag ev
        | ev < 0 =
          _ = sys close fd
          stop ag
          ConnClosed
        | ev >= 8 =
          _ = sys close fd
          stop ag
          ConnClosed
        | ev == 0 =
      conn drain outbound fd ag (try receive from ag)
        | otherwise =
          payload = sys read fd fd 65536
          conn feed payload fd ag payload

fn :: conn feed payload Int Agent String => StepOutcome
      conn feed payload fd ag "" =
        sys close fd -> ()
        stop ag
        ConnClosed
      conn feed payload fd ag data =
        send data to ag
        conn drain outbound fd ag (try receive from ag)

40.4.2. Implementació interna: Core Implementation Part 2

Fixa't en com net_agent.rg estructura les signatures fn :: ... => ... primer i resol cada cas mitjançant equacions alineades i crides de cua:

fn :: conn cast str A => String
      conn cast str x =  x

fn :: conn drain outbound Int Agent Option => StepOutcome
      conn drain outbound fd ag None = ConnKeep (ConnSlot fd ag) ""
      conn drain outbound fd ag (Some resp) =
        resp conn cast str -> s
        sys write fd fd s -> ()
        ConnKeep (ConnSlot fd ag) s

fn :: reactor sweep [ConnSlot]  => [ConnSlot]
      reactor sweep []          =  []
      reactor sweep (slot:rest) =
        slot conn poll step -> outcome
        rest reactor sweep -> kept
        reactor sweep next outcome kept

fn :: reactor sweep next StepOutcome       [ConnSlot] => [ConnSlot]
      reactor sweep next ConnClosed        kept       =  kept
      reactor sweep next (ConnKeep slot _) kept       =  [slot] :: kept

fn :: reactor shutdown [ConnSlot] => ()
      reactor shutdown []         =  ()
      reactor shutdown ((ConnSlot fd ag):rest) =
        sys close fd -> ()
        stop ag
        reactor shutdown rest

40.5. Garanties algorísmiques, memòria `RMM1`/`RMM2` i les 5 Regles d'Or de `net_agent`

Garantia algorísmica i de seguretat: Protecció automàtica enfront d'esgotament de descriptors (max_conns), expulsió determinista de connexions inactives i tancament garantit de sockets a net tcp echo step.
Complexitat de pila $O(1)$ amb TCO: Tots els bucles recursius a src/main/ridgun/lib/net_agent.rg estan en posició de cua, de manera que ridgunc els compila a salts natius sense creixement de pila.
Memòria determinista (RMM1/RMM2): Zero pauses de recol·lector de brossa; totes les estructures intermèdies s'alliberen de forma determinista en sortir de l'àmbit.
Verificació contínua: Provada exhaustivament amb stable check i la suite automatitzada src/test/ridgun/test net_agent.rg.

Les 5 Regles d'Or en programar amb `net_agent`

Declara import net_agent a l'inici del fitxer i aprofita l'equivalència entre espais i guions baixos perquè el teu codi es llegeixi com a prosa.
Alinea les teves canonades de dades amb =: encadena les crides a net_agent en passos amb nom propi i deixa que stable format alineï les columnes.
Aprofita les funcions totals de net_agent a les teves guardes |: comprova els valors de retorn o desembolica els ADTs amb pattern matching en lloc d'assumir que l'entrada externa sempre és vàlida.
Evita copiar grans estructures si només necessites consultar un camp: recorda que en RMM2 els arguments d'entrada no incrementen ni decrementen comptadors (+0 / -0).
Combina net_agent amb test (import test): escriu sempre assercions amb assert equals o assert true per fixar els invariants del teu domini.

Has completat el recorregut exhaustiu per les 32 libs estàndard de ridgun-libs! Ara tens a les teves mans totes les peces per construir aplicacions i eines de sistemes completes en Ridgun pur.

La lib net_agent — Supervisor de Connexions de Xarxa i Pont d'Esdeveniments No Bloquejant

40.1. Per què existeix la lib net_agent? (El problema real i la filosofia Ridgun)

40.2. Artefactes natius, importació i catàleg complet de l'API de net_agent

40.2.1. Resum de famílies funcionals de net_agent

40.2.2. Catàleg exhaustiu de tipus i signatures a src/main/ridgun/lib/net_agent.rg

40.3. Explorant net_agent a fons: Exemples pas a pas de cada funcionalitat

40.3.1. Exemple 1: Flux principal en estil tabular amb net_agent

40.3.2. Exemple 2: Composició segura i gestió de casos de vora

40.3.3. Exemple 3: Combinadors d'actors (agent ask, try ask, send batch, map batch, drain ready), pools particionats i reactor de connexions

40.3.4. Exemple 4: Cicle de vida d'agents (is agent alive, agent status, stop agent) i agent comptador amb estat aïllat (new counter agent)

40.3.5. Exemple 5: Agent de bitàcola append-only (new log agent) i magatzem clau-valor en memòria per pas de missatges (new kv agent)

40.3.6. Exemple 6: Sondeig no bloquejant de descriptors (conn poll step), escombrat de taula de connexions (reactor sweep) i apagada neta (reactor shutdown)

40.4. Sota el capó: com està construïda net_agent en Ridgun pur (src/main/ridgun/lib/net_agent.rg)

40.4.1. Implementació interna: Core Implementation Part 1

40.4.2. Implementació interna: Core Implementation Part 2

40.5. Garanties algorísmiques, memòria RMM1/RMM2 i les 5 Regles d'Or de net_agent

Les 5 Regles d'Or en programar amb net_agent

La lib `net_agent` — Supervisor de Connexions de Xarxa i Pont d'Esdeveniments No Bloquejant

40.1. Per què existeix la lib `net_agent`? (El problema real i la filosofia Ridgun)

40.2. Artefactes natius, importació i catàleg complet de l'API de `net_agent`

40.2.1. Resum de famílies funcionals de `net_agent`

40.2.2. Catàleg exhaustiu de tipus i signatures a `src/main/ridgun/lib/net_agent.rg`

40.3. Explorant `net_agent` a fons: Exemples pas a pas de cada funcionalitat

40.3.1. Exemple 1: Flux principal en estil tabular amb `net_agent`

40.3.3. Exemple 3: Combinadors d'actors (`agent ask`, `try ask`, `send batch`, `map batch`, `drain ready`), pools particionats i reactor de connexions

40.3.4. Exemple 4: Cicle de vida d'agents (`is agent alive`, `agent status`, `stop agent`) i agent comptador amb estat aïllat (`new counter agent`)

40.3.5. Exemple 5: Agent de bitàcola append-only (`new log agent`) i magatzem clau-valor en memòria per pas de missatges (`new kv agent`)

40.3.6. Exemple 6: Sondeig no bloquejant de descriptors (`conn poll step`), escombrat de taula de connexions (`reactor sweep`) i apagada neta (`reactor shutdown`)

40.4. Sota el capó: com està construïda `net_agent` en Ridgun pur (`src/main/ridgun/lib/net_agent.rg`)

40.5. Garanties algorísmiques, memòria `RMM1`/`RMM2` i les 5 Regles d'Or de `net_agent`

Les 5 Regles d'Or en programar amb `net_agent`