pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/channels/_chooser.py

@@ -0,0 +1,45 @@
+"""Which worker of a fleet a call is offered to: one heard lately, with a seat free, the freest."""
+
+from collections.abc import Collection, Mapping
+
+from pinecall.fleet.roster import REFUSED_AT, accepting_of
+from pinecall.wire.rest.fleet import WorkerStatus
+
+# Two heartbeats and a margin: a worker unheard this long may be gone, and LiveKit would keep a
+# dead one for 15 minutes; it is not offered a call until it is heard again.
+HEARD_WITHIN_S = 12.0
+
+
+def chosen(
+    seats: Collection[WorkerStatus],
+    in_flight: Mapping[str, int],
+    now: float,
+    not_these: Collection[str] = (),
+) -> WorkerStatus | None:
+    """The worker to offer a call to, or None when no worker of the fleet has a seat."""
+    candidates = [
+        seat
+        for seat in accepting_of(seats, now)
+        if seat.agent_name is not None
+        and seat.agent_name not in not_these
+        and now - seat.seen_at <= HEARD_WITHIN_S
+        and free_seats(seat, in_flight) > 0
+    ]
+    return max(candidates, key=lambda seat: (free_seats(seat, in_flight), -seat.load), default=None)
+
+
+# A gateway that just started rebuilds its roster from the next heartbeats, five seconds: until a
+# worker of the fleet is heard, nobody can say the fleet is full.
+def any_heard(seats: Collection[WorkerStatus], now: float) -> bool:
+    """Whether any worker of the fleet was heard lately, whatever it is doing."""
+    return any(now - seat.seen_at <= HEARD_WITHIN_S for seat in seats)
+
+
+# A worker gated on its CPU has no count of seats: one call at a time is offered to it, under
+# LiveKit's line.
+def free_seats(seat: WorkerStatus, in_flight: Mapping[str, int]) -> int:
+    """The seats a worker has free, its calls and the ones offered to it not yet opened taken."""
+    offered = in_flight.get(seat.agent_name or "", 0)
+    if seat.max_jobs is None:
+        return 1 if seat.load < REFUSED_AT and offered == 0 else 0
+    return seat.max_jobs - seat.active - offered

pinecall/channels/offers.py

@@ -0,0 +1,219 @@
+"""Who takes a call: offered to a worker the gateway chose, then another, then the overflow."""
+
+import logging
+import time
+from collections.abc import Mapping
+from dataclasses import dataclass
+
+from livekit import api
+
+from pinecall.channels import rooms
+from pinecall.channels._chooser import HEARD_WITHIN_S, any_heard, chosen, free_seats
+from pinecall.channels.rooms import Dispatch
+from pinecall.domain.names import Env
+from pinecall.fleet import worlds
+from pinecall.fleet.roster import Roster, overflow_name
+from pinecall.postgres.pool import Pool
+
+logger = logging.getLogger(__name__)
+
+# LiveKit waits 10 s on a worker that does not answer before it gives a job up; a live worker opens
+# its call in about 2 s. A room no worker opened 12 s after its offer is offered to another.
+OFFERED_AGAIN_AFTER_S = 12.0
+
+# Three offers, then the overflow's sentence: 36 s is the longest a caller waits on our account.
+OFFERS = 3
+
+# A fleet none of whose workers was heard is one the gateway knows nothing of yet (it just
+# started): the room waits for the next sweep, up to as long as a worker takes to be heard.
+WAITS_FOR_A_WORKER_S = HEARD_WITHIN_S
+
+# The rooms counted as waiting for a worker: the ones a caller joined in the last ten minutes.
+WAITING_COUNTED_S = 600.0
+
+# Every room is done with by its third offer and a sweep after it: one kept a minute is a room no
+# gateway is sweeping.
+UNSWEPT_AFTER_S = 60.0
+
+UNSWEPT = "{n} rooms a caller joined over a minute ago were never let go: no gateway sweeps them"
+
+# The first sight stands: a second webhook for the same room changes nothing.
+OPENED = """
+INSERT INTO offers (room, fleet, dispatch, seen_at)
+VALUES (%(room)s, %(fleet)s, %(dispatch)s, %(now)s)
+ON CONFLICT (room) DO NOTHING
+RETURNING room
+"""
+
+# Taken only by the gateway that read this count: two sweeping the same room offer it once.
+CLAIMED = """
+UPDATE offers SET worker = %(worker)s, offers = offers + 1, offered_at = %(now)s
+WHERE room = %(room)s AND offers = %(offers)s
+RETURNING room
+"""
+
+DUE = """
+SELECT room, fleet, dispatch, seen_at, worker, offers FROM offers
+WHERE offered_at IS NULL OR offered_at < %(before)s
+ORDER BY seen_at LIMIT %(limit)s
+"""
+
+IN_FLIGHT = """
+SELECT worker, count(*) AS offered FROM offers
+WHERE worker IS NOT NULL AND offered_at >= %(since)s
+GROUP BY worker
+"""
+
+WAITING = """
+SELECT fleet, count(*) AS waiting FROM offers WHERE seen_at >= %(since)s GROUP BY fleet
+"""
+
+FORGOTTEN = "DELETE FROM offers WHERE room = %(room)s"
+
+AGED = "DELETE FROM offers WHERE seen_at < %(before)s"
+
+KEPT_SINCE = "SELECT count(*) AS kept FROM offers WHERE seen_at < %(before)s"
+
+OFFERED = "room %s: offered to %s: %s"
+
+NOT_YET = "room %s: %s; offered at the next sweep"
+
+OFFERED_AGAIN = "room %s: no worker opened it in %.0f s; offered to %s (offer %d): %s"
+
+TO_THE_OVERFLOW = "room %s: %s; the overflow says the sentence"
+
+NO_WORLD = "room %s: fleet %s is no world's, so no LiveKit holds its room; not offered"
+
+
+@dataclass(frozen=True)
+class Offer:
+    """A room waiting for a worker: its fleet, its call's dispatch, and whom it was offered to."""
+
+    room: str
+    fleet: str
+    dispatch: str
+    seen_at: float
+    worker: str | None
+    offers: int
+
+
+# What a process holds to send a call to a worker: the offers' table, each world's LiveKit, and
+# the fleet's workers as their heartbeats say. Every door that sends a call into a room goes
+# through it. A room lives on the LiveKit of its fleet's world, which the fleets row says.
+@dataclass(frozen=True)
+class Offering:
+    """The gateway's dispatcher: a room offered to the worker it chose, by the worker's name."""
+
+    pool: Pool
+    servers: Mapping[Env, api.LiveKitAPI]
+    roster: Roster
+
+    async def offer(self, room: str, fleet: str, dispatch: Dispatch) -> str | None:
+        """Keep the room and offer it; the name it went to, or None if kept already or not yet."""
+        written = rooms.written(dispatch)
+        now = time.time()
+        if not await opened(self.pool, room, fleet, written, now):
+            return None
+        return await self.offered(
+            Offer(room=room, fleet=fleet, dispatch=written, seen_at=now, worker=None, offers=0)
+        )
+
+    async def offered(self, offer: Offer) -> str | None:
+        """Offer the room to the worker it should go to now; the name, or None if not offered."""
+        now = time.time()
+        world = worlds.world_of(await worlds.fleets(self.pool), offer.fleet)
+        if world is None:
+            logger.warning(NO_WORLD, offer.room, offer.fleet)
+            return None
+        target, why = await _target(self.pool, self.roster, offer, now)
+        if target is None:
+            logger.info(NOT_YET, offer.room, why)
+            return None
+        if not await claimed(self.pool, offer, target, now):
+            return None
+        dispatch = rooms.read_dispatch(offer.dispatch)
+        await rooms.dispatched(self.servers[world], offer.room, target, dispatch)
+        if target == overflow_name(offer.fleet):
+            await forgotten(self.pool, offer.room)
+            logger.warning(TO_THE_OVERFLOW, offer.room, why)
+        elif offer.offers > 0:
+            logger.warning(
+                OFFERED_AGAIN, offer.room, OFFERED_AGAIN_AFTER_S, target, offer.offers + 1, why
+            )
+        else:
+            logger.info(OFFERED, offer.room, target, why)
+        return target
+
+
+async def opened(pool: Pool, room: str, fleet: str, dispatch: str, now: float) -> bool:
+    """Keep a room a caller joined; False when it was kept already."""
+    values = {"room": room, "fleet": fleet, "dispatch": dispatch, "now": now}
+    async with pool.connection() as connection:
+        return await (await connection.execute(OPENED, values)).fetchone() is not None
+
+
+async def claimed(pool: Pool, offer: Offer, worker: str, now: float) -> bool:
+    """Say the room is offered to this worker; False when another gateway offered it first."""
+    values = {"room": offer.room, "worker": worker, "offers": offer.offers, "now": now}
+    async with pool.connection() as connection:
+        return await (await connection.execute(CLAIMED, values)).fetchone() is not None
+
+
+async def due(pool: Pool, before: float, limit: int) -> list[Offer]:
+    """The rooms no worker opened and nobody offered since `before`, oldest first."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(DUE, {"before": before, "limit": limit})).fetchall()
+    return [Offer(**row) for row in rows]
+
+
+async def in_flight(pool: Pool, since: float) -> dict[str, int]:
+    """Each worker's rooms offered since `since` that it has not opened."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(IN_FLIGHT, {"since": since})).fetchall()
+    return {row["worker"]: row["offered"] for row in rows}
+
+
+async def waiting(pool: Pool, since: float) -> dict[str, int]:
+    """Each fleet's rooms with a caller seen since `since` that no worker opened."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(WAITING, {"since": since})).fetchall()
+    return {row["fleet"]: row["waiting"] for row in rows}
+
+
+async def forgotten(pool: Pool, room: str) -> None:
+    """The room is done with: its call opened, the overflow sent, or the room gone."""
+    async with pool.connection() as connection:
+        await connection.execute(FORGOTTEN, {"room": room})
+
+
+async def aged_out(pool: Pool, before: float) -> None:
+    """Rooms first seen before `before` are past any offer: their callers are gone."""
+    async with pool.connection() as connection:
+        await connection.execute(AGED, {"before": before})
+
+
+async def examined(pool: Pool, now: float) -> str | None:
+    """What doctor says of the offers: the rooms kept past every offer, or None."""
+    async with pool.connection() as connection:
+        row = await (
+            await connection.execute(KEPT_SINCE, {"before": now - UNSWEPT_AFTER_S})
+        ).fetchone()
+    kept = 0 if row is None else row["kept"]
+    return UNSWEPT.format(n=kept) if kept else None
+
+
+# The worker chosen; the overflow when the offers ran out or the workers heard have no seat; None
+# while no worker of the fleet was heard yet. And why, so the log says it.
+async def _target(pool: Pool, roster: Roster, offer: Offer, now: float) -> tuple[str | None, str]:
+    if offer.offers >= OFFERS:
+        return overflow_name(offer.fleet), f"no worker opened it in {OFFERS} offers"
+    flying = await in_flight(pool, now - OFFERED_AGAIN_AFTER_S)
+    tried = () if offer.worker is None else (offer.worker,)
+    seats = roster.of(offer.fleet, now)
+    seat = chosen(seats, flying, now, not_these=tried)
+    if seat is not None and seat.agent_name is not None:
+        free = free_seats(seat, flying)
+        return seat.agent_name, f"{free} seats free, heard {now - seat.seen_at:.0f} s ago"
+    if not any_heard(seats, now) and now - offer.seen_at < WAITS_FOR_A_WORKER_S:
+        return None, f"no worker of the fleet heard in {HEARD_WITHIN_S:.0f} s"
+    return overflow_name(offer.fleet), "no worker of the fleet has a seat"

pinecall/channels/rooms.py

@@ -0,0 +1,176 @@
+"""The dispatch to a world's fleet, the rooms an agent is in, and LiveKit's signed events."""
+
+import json
+from collections.abc import Collection, Mapping
+
+from google.protobuf.json_format import ParseDict, ParseError
+from livekit import api
+from livekit.protocol.agent_dispatch import RoomAgentDispatch
+from livekit.protocol.room import RoomConfiguration
+from livekit.protocol.webhook import WebhookEvent
+from pydantic import BaseModel, ConfigDict, Field, ValidationError
+
+from pinecall.domain.errors import DeclarationRefused, NotAllowed
+from pinecall.domain.names import Direction, Env, Json, JsonObject
+
+NOT_A_ROOM_CONFIG = "room_config is not a LiveKit RoomConfiguration: {reason}"
+
+# Room names ride one request's query, so they are params for in batches.
+ROOMS_A_REQUEST = 100
+
+# livekit's code for a room that is not there.
+ROOM_GONE = "not_found"
+
+UNSIGNED = "the event carries no signature of this box's LiveKit key: {reason}"
+
+# The seats a person sits in: a browser's, and a phone's leg.
+A_PERSON = frozenset({api.ParticipantInfo.Kind.STANDARD, api.ParticipantInfo.Kind.SIP})
+
+
+# `trunk` names the carrier account the leg is dialled through; the worker asks the gateway for
+# its inline configuration, so no secret rides a dispatch.
+class Dialling(BaseModel):
+    """The leg an outbound job places: trunk, far end, the number shown, the media's ceiling."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore")
+
+    trunk: str
+    to: str
+    shown: str
+    max_duration_s: int = 0
+
+
+# Written by the gateway alone, signed into a token or sent by the server API, so the worker
+# trusts it: the scope a call runs in, and on an outbound call the ceiling of its leg.
+class Dispatch(BaseModel):
+    """What a dispatch tells the job it starts: whose call, which agent, and how it arrived."""
+
+    model_config = ConfigDict(frozen=True, extra="ignore", populate_by_name=True)
+
+    agent: str | None = None
+    org: str | None = None
+    env: Env | None = None
+    holder: str | None = None
+    direction: Direction = "inbound"
+    caller: str | None = None
+    # An opaque id the tenant's backend knows the visitor by; never a number or a name.
+    contact: str | None = None
+    # The token's scope: a dispatch that carries one spends its token once.
+    scope: str | None = None
+    # What the tenant's backend sealed into the token.
+    metadata: JsonObject = Field(default_factory=dict[str, Json])
+    dial: Dialling | None = None
+    # The app socket that must serve the call (a spoken golden run).
+    app: str | None = None
+    # A simulated caller and its rules, frozen at dispatch so a later edit does not move them.
+    run: str | None = None
+    persona: str | None = None
+    accepts_when: str | None = None
+    declines_when: str | None = None
+    diverted_from: Env | None = None
+    # The state the call opens in, when a golden or a persona asked for one.
+    state: JsonObject = Field(default_factory=dict[str, Json])
+    # The call's worker went away mid-call: the job tells the caller once and closes the room.
+    worker_gone: bool = False
+    # How many entries the log took from the worker that went: where the told job's writer follows.
+    entries_written: int = 0
+
+
+def written(dispatch: Dispatch) -> str:
+    """The dispatch as a job's metadata: compact JSON, absent fields absent."""
+    data = dispatch.model_dump(mode="json", exclude_none=True, exclude_defaults=True)
+    return json.dumps(data, separators=(",", ":"))
+
+
+# A job with no metadata or with somebody else's (a room nobody dispatched) reads as empty.
+def read_dispatch(metadata: str) -> Dispatch:
+    """The dispatch a job was started with."""
+    if not metadata:
+        return Dispatch()
+    try:
+        return Dispatch.model_validate_json(metadata)
+    except ValidationError:
+        return Dispatch()
+
+
+# livekit creates the dispatch from the token when the join creates the room, so the browser
+# cannot change the agent, the org or the world it reaches.
+def room_dispatch(fleet: str, dispatch: Dispatch) -> RoomConfiguration:
+    """The room configuration a visitor's token carries: one dispatch, to the world's fleet."""
+    return RoomConfiguration(
+        agents=[RoomAgentDispatch(agent_name=fleet, metadata=written(dispatch))]
+    )
+
+
+# livekit creates the room if it does not exist; its name is the call id the worker opens.
+async def dispatched(server: api.LiveKitAPI, room: str, agent: str, dispatch: Dispatch) -> None:
+    """Send the workers registered under this name into a room, with the call's dispatch."""
+    await server.agent_dispatch.create_dispatch(
+        api.CreateAgentDispatchRequest(room=room, agent_name=agent, metadata=written(dispatch))
+    )
+
+
+# A stock livekit client names the agent as room_config.agents[0].agent_name, in either spelling.
+def client_named_agent(room_config: Mapping[str, object] | None) -> str | None:
+    """The agent a livekit client put in the room configuration, or None."""
+    if not room_config:
+        return None
+    try:
+        parsed = ParseDict(dict(room_config), RoomConfiguration(), ignore_unknown_fields=True)
+    except ParseError as malformed:
+        raise DeclarationRefused(NOT_A_ROOM_CONFIG.format(reason=malformed)) from malformed
+    agents = list(parsed.agents)
+    return (agents[0].agent_name or None) if agents else None
+
+
+# A room is a live call only while an agent is in it: a browser tab or a supervisor keeps a
+# room open long after its job is gone.
+async def rooms_with_an_agent(server: api.LiveKitAPI, names: Collection[str]) -> set[str]:
+    """The rooms of these that exist with an agent in them."""
+    wanted = list(names)
+    served: set[str] = set()
+    for start in range(0, len(wanted), ROOMS_A_REQUEST):
+        batch = wanted[start : start + ROOMS_A_REQUEST]
+        rooms = await server.room.list_rooms(api.ListRoomsRequest(names=batch))
+        for room in rooms.rooms:
+            seats = await server.room.list_participants(api.ListParticipantsRequest(room=room.name))
+            if any(seat.kind == api.ParticipantInfo.Kind.AGENT for seat in seats.participants):
+                served.add(room.name)
+    return served
+
+
+async def room_closed(server: api.LiveKitAPI, name: str) -> None:
+    """Delete the room, which hangs up everyone still in it; a room already gone is fine."""
+    try:
+        await server.room.delete_room(api.DeleteRoomRequest(room=name))
+    except api.TwirpError as refused:
+        if refused.code != ROOM_GONE:
+            raise
+
+
+# A room gone is nobody left in it.
+async def seats_in(server: api.LiveKitAPI, name: str) -> list[api.ParticipantInfo]:
+    """Who is in the room: nobody when it is gone."""
+    try:
+        seats = await server.room.list_participants(api.ListParticipantsRequest(room=name))
+    except api.TwirpError as refused:
+        if refused.code != ROOM_GONE:
+            raise
+        return []
+    return list(seats.participants)
+
+
+async def left_alone(server: api.LiveKitAPI, name: str) -> bool:
+    """Whether a person is still in the room and no agent is."""
+    kinds = {seat.kind for seat in await seats_in(server, name)}
+    return api.ParticipantInfo.Kind.AGENT not in kinds and bool(kinds & A_PERSON)
+
+
+# livekit signs each event with a key of the server's: a token whose sha256 claim is the body's.
+# The library raises a bare Exception for a body that does not match its token.
+def livekit_event(body: str, token: str, key: str, secret: str) -> WebhookEvent:
+    """The event of a body LiveKit signed with this key, or NotAllowed."""
+    try:
+        return api.WebhookReceiver(api.TokenVerifier(key, secret)).receive(body, token)
+    except Exception as refused:
+        raise NotAllowed(UNSIGNED.format(reason=refused)) from refused