pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/tenancy/canary.py

@@ -0,0 +1,126 @@
+"""A version of an agent's settings on a share of its calls: set, cleared, which calls take it."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from hashlib import sha256
+
+from pinecall.domain.scope import Scope
+from pinecall.postgres.pool import Pool
+
+# A share is a whole percent of the scope's calls.
+ALL_CALLS = 100
+
+
+STANDING = """
+SELECT holder, version, share, author, note, set_at FROM agent_canaries
+WHERE org = %(org)s AND env = %(env)s AND holder = %(holder)s AND agent = %(agent)s
+ORDER BY set_at DESC, id DESC
+LIMIT 1
+"""
+
+
+# Only ever added: a version and a share set it, a row with neither clears it.
+# Stamped by the log's clock, as a call's head is, so which came first is one clock's word.
+PUT = """
+INSERT INTO agent_canaries (org, env, holder, agent, version, share, author, note, set_at)
+VALUES (%(org)s, %(env)s, %(holder)s, %(agent)s, %(version)s, %(share)s, %(author)s, %(note)s,
+        to_timestamp(%(at)s))
+"""
+
+
+# The canary each level of the call's scope had when the call opened.
+STOOD_AT = """
+SELECT DISTINCT ON (holder) holder, version, share FROM agent_canaries
+WHERE org = %(org)s AND env = %(env)s AND holder IN (%(holder)s, '') AND agent = %(agent)s
+  AND set_at <= to_timestamp(%(at)s)
+ORDER BY holder, set_at DESC, id DESC
+"""
+
+
+@dataclass(frozen=True)
+class Canary:
+    """Which version takes a share of the calls, and how many in a hundred."""
+
+    version: int
+    share: int
+
+
+@dataclass(frozen=True)
+class CanarySet:
+    """A canary as written: the version and share, or None to clear it, who, when and why."""
+
+    canary: Canary | None
+    author: str
+    at: float
+    note: str | None = None
+
+
+@dataclass(frozen=True)
+class Current:
+    """The canary a scope stands on now: whose, which, who set it, why and when."""
+
+    holder: str
+    canary: Canary
+    author: str
+    note: str | None
+    set_at: datetime
+
+
+# sha256, not hash(): the same call lands in the same place in every process and every release,
+# so a call asked for again (a gateway that restarted) keeps its version.
+def bucket_of(call: str) -> int:
+    """The call's place among a hundred; a canary of share N takes the places under N."""
+    return int(sha256(call.encode()).hexdigest()[:8], 16) % ALL_CALLS
+
+
+async def current(pool: Pool, scope: Scope, agent: str) -> Current | None:
+    """The scope's own canary for the agent, or None when none stands or it was cleared."""
+    params = {"org": scope.org, "env": scope.env, "holder": scope.holder, "agent": agent}
+    async with pool.connection() as connection:
+        row = await (await connection.execute(STANDING, params)).fetchone()
+    if row is None or row["version"] is None:
+        return None
+    return Current(
+        holder=row["holder"],
+        canary=Canary(version=row["version"], share=row["share"]),
+        author=row["author"],
+        note=row["note"],
+        set_at=row["set_at"],
+    )
+
+
+async def put(pool: Pool, scope: Scope, agent: str, written: CanarySet) -> None:
+    """Set the scope's canary for the agent, or clear it."""
+    wanted = written.canary
+    params = {
+        "org": scope.org,
+        "env": scope.env,
+        "holder": scope.holder,
+        "agent": agent,
+        "version": None if wanted is None else wanted.version,
+        "share": None if wanted is None else wanted.share,
+        "author": written.author,
+        "note": written.note,
+        "at": written.at,
+    }
+    async with pool.connection() as connection:
+        await connection.execute(PUT, params)
+
+
+# A call runs the canary's version only when it was picked for it: the rest never run it.
+async def ran_the_canary(
+    pool: Pool, scope: Scope, agent: str, version: int | None, at: float
+) -> bool:
+    """Whether a call that opened then on this version was one of a canary's share."""
+    if version is None:
+        return False
+    params = {
+        "org": scope.org,
+        "env": scope.env,
+        "holder": scope.holder,
+        "agent": agent,
+        "at": at,
+    }
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(STOOD_AT, params)).fetchall()
+    return any(row["version"] == version and row["share"] for row in rows)

pinecall/tenancy/carrier_networks.py

@@ -0,0 +1,156 @@
+"""The networks an org asks the box to open 5060 to, and the operator's answer to each."""
+
+from collections.abc import Sequence
+from dataclasses import dataclass
+from ipaddress import IPv4Network, ip_network
+from typing import Literal
+
+from psycopg.rows import DictRow
+
+from pinecall.domain.errors import DeclarationRefused, NotFound
+from pinecall.postgres.pool import Pool
+
+type NetworkState = Literal["waiting", "approved", "refused"]
+
+
+# A carrier's edge is a few addresses; anything wider is a network nobody vouches for.
+WIDEST = 24
+
+
+NOT_A_NETWORK = "{network} is not an IPv4 address or network, like 198.51.100.7/32"
+
+
+TOO_WIDE = "{network} is wider than a /{widest}: name the addresses your PBX or carrier calls from"
+
+
+NOT_PUBLIC = "{network} is not a public address: a carrier reaches the box from the internet"
+
+
+NO_SUCH_ASK = "no network was asked for with id {ask}"
+
+
+ASK = """
+INSERT INTO carrier_networks (org, source, network) VALUES (%(org)s, %(source)s, %(network)s)
+ON CONFLICT (org, source, network) DO NOTHING
+"""
+FORGET = """
+DELETE FROM carrier_networks
+WHERE org = %(org)s AND source = %(source)s AND NOT (network = ANY(%(networks)s::cidr[]))
+"""
+OF_SOURCE = """
+SELECT id, org, source, network, state, asked_at, decided_by, decided_at FROM carrier_networks
+WHERE org = %(org)s AND source = %(source)s ORDER BY asked_at, network
+"""
+OF_ORG = """
+SELECT id, org, source, network, state, asked_at, decided_by, decided_at FROM carrier_networks
+WHERE org = %(org)s ORDER BY asked_at, network
+"""
+LISTED = """
+SELECT id, org, source, network, state, asked_at, decided_by, decided_at FROM carrier_networks
+ORDER BY asked_at, id
+"""
+IN_STATE = """
+SELECT id, org, source, network, state, asked_at, decided_by, decided_at FROM carrier_networks
+WHERE state = %(state)s ORDER BY asked_at, id
+"""
+DECIDE = """
+UPDATE carrier_networks SET state = %(state)s, decided_by = %(by)s, decided_at = now()
+WHERE id = %(id)s RETURNING id, org, source, network, state, asked_at, decided_by, decided_at
+"""
+
+
+@dataclass(frozen=True)
+class NetworkAsk:
+    """A network an org asked for: what asked, the network, and where the operator stands on it."""
+
+    id: int
+    org: str
+    source: str
+    network: str
+    state: NetworkState
+    asked_at: float
+    decided_by: str | None
+    decided_at: float | None
+
+
+def checked(network: str) -> str:
+    """The network written the one way, or DeclarationRefused saying why it cannot be admitted."""
+    try:
+        parsed = ip_network(network.strip(), strict=False)
+    except ValueError:
+        raise DeclarationRefused(NOT_A_NETWORK.format(network=network)) from None
+    if not isinstance(parsed, IPv4Network):
+        raise DeclarationRefused(NOT_A_NETWORK.format(network=network))
+    if parsed.prefixlen < WIDEST:
+        raise DeclarationRefused(TOO_WIDE.format(network=parsed, widest=WIDEST))
+    if not parsed.is_global:
+        raise DeclarationRefused(NOT_PUBLIC.format(network=parsed))
+    return str(parsed)
+
+
+def written(network: str) -> str:
+    """The network as the table writes it (an address is a /32), or as given when it is none."""
+    try:
+        return str(ip_network(network.strip(), strict=False))
+    except ValueError:
+        return network
+
+
+async def ask(pool: Pool, org: str, source: str, networks: Sequence[str]) -> list[NetworkAsk]:
+    """Ask for these networks for the source, forgetting the ones it no longer names; its rows."""
+    wanted = [checked(network) for network in networks]
+    params = {"org": org, "source": source, "networks": wanted}
+    async with pool.connection() as connection, connection.transaction():
+        for network in wanted:
+            await connection.execute(ASK, {"org": org, "source": source, "network": network})
+        await connection.execute(FORGET, params)
+        rows = await (await connection.execute(OF_SOURCE, params)).fetchall()
+    return [_ask(row) for row in rows]
+
+
+async def of_org(pool: Pool, org: str) -> list[NetworkAsk]:
+    """Every network the org asked for, oldest first."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(OF_ORG, {"org": org})).fetchall()
+    return [_ask(row) for row in rows]
+
+
+async def approved(pool: Pool, org: str) -> dict[str, tuple[str, ...]]:
+    """The networks approved for each source of the org."""
+    found: dict[str, tuple[str, ...]] = {}
+    for row in await of_org(pool, org):
+        if row.state == "approved":
+            found[row.source] = (*found.get(row.source, ()), row.network)
+    return found
+
+
+async def listed(pool: Pool, state: NetworkState | None = None) -> list[NetworkAsk]:
+    """Every network asked for on the box, or those in one state, oldest first."""
+    query, params = (LISTED, {}) if state is None else (IN_STATE, {"state": state})
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(query, params)).fetchall()
+    return [_ask(row) for row in rows]
+
+
+async def decide(pool: Pool, ask_id: int, state: NetworkState, by: str) -> NetworkAsk:
+    """Approve or refuse a network asked for; NotFound for an id nobody asked with."""
+    async with pool.connection() as connection:
+        row = await (
+            await connection.execute(DECIDE, {"id": ask_id, "state": state, "by": by})
+        ).fetchone()
+    if row is None:
+        raise NotFound(NO_SUCH_ASK.format(ask=ask_id))
+    return _ask(row)
+
+
+def _ask(row: DictRow) -> NetworkAsk:
+    return NetworkAsk(
+        id=int(row["id"]),
+        org=str(row["org"]),
+        source=str(row["source"]),
+        network=str(row["network"]),
+        state=row["state"],
+        asked_at=row["asked_at"].timestamp(),
+        decided_by=row["decided_by"],
+        decided_at=None if row["decided_at"] is None else row["decided_at"].timestamp(),
+    )

pinecall/tenancy/carriers.py

@@ -0,0 +1,265 @@
+"""An org's carrier accounts (Twilio, a SIP peer, WhatsApp at Meta), sealed; the box's Twilio."""
+
+import logging
+from dataclasses import dataclass, replace
+from ipaddress import ip_network
+from typing import Annotated, Literal, Self
+
+from cryptography.fernet import MultiFernet
+from psycopg.rows import DictRow
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    TypeAdapter,
+    ValidationError,
+    field_validator,
+    model_validator,
+)
+
+from pinecall.domain.errors import Conflict, NotAvailable, NotFound
+from pinecall.postgres.pool import Pool
+from pinecall.tenancy import vault
+
+type Transport = Literal["auto", "udp", "tcp", "tls"]
+
+
+logger = logging.getLogger(__name__)
+
+
+# The box's own Twilio account, sealed in box_settings as credentials/twilio.
+BOX_ACCOUNT = "twilio"
+
+
+NO_CARRIER = "the org has no carrier account: PUT /v1/carrier brings a Twilio account or a SIP peer"
+
+
+NO_SUCH_ACCOUNT = "the org has no carrier account {account}"
+
+
+WHICH_ACCOUNT = "the org has {count} carrier accounts ({accounts}): name one of them"
+
+
+NO_BOX_TWILIO = (
+    "this box buys no numbers: it has no Twilio account of its own. Bring a carrier and import one"
+)
+
+
+NOT_A_NETWORK = "{address} is not a network a peer calls from, like 203.0.113.0/24"
+
+
+HALF_A_PAIR = "outbound_username is given without outbound_password: a peer is dialled with both"
+
+
+A_SID = r"^(AC|SK)[0-9a-fA-F]{32}$"
+
+
+AN_ACCOUNT_SID = r"^AC[0-9a-fA-F]{32}$"
+
+
+CARRIERS = (
+    "SELECT kind, account, ciphertext FROM carriers WHERE org = %(org)s ORDER BY set_at, account"
+)
+CARRIER = (
+    "SELECT kind, account, ciphertext FROM carriers WHERE org = %(org)s AND account = %(account)s"
+)
+
+
+PUT_CARRIER = """
+INSERT INTO carriers (org, kind, account, label, ciphertext)
+VALUES (%(org)s, %(kind)s, %(account)s, %(label)s, %(ciphertext)s)
+ON CONFLICT (org, account) DO UPDATE SET kind = excluded.kind, label = excluded.label,
+    ciphertext = excluded.ciphertext, set_at = now()
+"""
+
+
+DROP_CARRIER = (
+    "DELETE FROM carriers WHERE org = %(org)s AND account = %(account)s RETURNING account"
+)
+
+
+class TwilioAccount(BaseModel):
+    """A Twilio account: its SID, and an API key SID with its secret (or the SID and auth token)."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: Literal["twilio"] = "twilio"
+    account_sid: Annotated[str, Field(pattern=AN_ACCOUNT_SID)]
+    user: Annotated[str, Field(pattern=A_SID)]
+    secret: Annotated[str, Field(min_length=1)]
+    label: str = ""
+
+
+class SipPeer(BaseModel):
+    """A PBX or carrier that speaks SIP: where it calls from, its pair, where it is dialled."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: Literal["sip"] = "sip"
+    username: Annotated[str, Field(min_length=1)]
+    password: Annotated[str, Field(min_length=1)]
+    addresses: Annotated[list[str], Field(min_length=1)]
+    outbound_host: str | None = None
+    outbound_transport: Transport = "auto"
+    outbound_username: str | None = None
+    outbound_password: str | None = None
+    label: str = ""
+
+    @field_validator("addresses")
+    @classmethod
+    def _networks(cls, addresses: list[str]) -> list[str]:
+        for address in addresses:
+            try:
+                ip_network(address, strict=False)
+            except ValueError:
+                raise ValueError(NOT_A_NETWORK.format(address=address)) from None
+        return addresses
+
+    # One account in both directions is what most carriers sell: unsaid, the inbound pair dials.
+    @model_validator(mode="after")
+    def _a_whole_pair(self) -> Self:
+        if self.outbound_username and not self.outbound_password:
+            raise ValueError(HALF_A_PAIR)
+        return self
+
+
+class WhatsappAccount(BaseModel):
+    """A WhatsApp number at Meta: the id replies are sent from, and the org's token."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    kind: Literal["whatsapp"] = "whatsapp"
+    phone_number_id: Annotated[str, Field(min_length=1)]
+    access_token: Annotated[str, Field(min_length=1)]
+    label: str = ""
+
+
+type Account = Annotated[TwilioAccount | SipPeer | WhatsappAccount, Field(discriminator="kind")]
+
+
+class Termination(BaseModel):
+    """How the box dials out through a Twilio account: the host and the credential it made."""
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    host: str
+    username: str
+    password: str
+
+
+class _Sealed(BaseModel):
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    account: Account
+    outbound: Termination | None = None
+
+
+@dataclass(frozen=True)
+class Carrier:
+    """One account of the org at an outside party that holds its numbers."""
+
+    org: str
+    account: TwilioAccount | SipPeer | WhatsappAccount
+    # Twilio only, written by provisioning: Twilio shows a credential's password once.
+    outbound: Termination | None = None
+
+    @property
+    def id(self) -> str:
+        """The account's own id: Twilio's SID, the peer's username, Meta's phone number id."""
+        match self.account:
+            case TwilioAccount():
+                return self.account.account_sid
+            case SipPeer():
+                return self.account.username
+            case WhatsappAccount():
+                return self.account.phone_number_id
+
+
+ACCOUNT: TypeAdapter[TwilioAccount | SipPeer | WhatsappAccount] = TypeAdapter(Account)
+
+
+async def carriers_of(pool: Pool, sealed: MultiFernet, org: str) -> list[Carrier]:
+    """The org's carrier accounts, oldest first, opened; one sealed under a lost key is skipped."""
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(CARRIERS, {"org": org})).fetchall()
+    opened = (_open_carrier(sealed, org, row) for row in rows)
+    return [carrier for carrier in opened if carrier is not None]
+
+
+async def carrier_named(
+    pool: Pool, sealed: MultiFernet, org: str, account: str | None = None
+) -> Carrier:
+    """The account named, or the org's only one; NotFound or Conflict otherwise."""
+    statement = CARRIERS if account is None else CARRIER
+    async with pool.connection() as connection:
+        rows = await (
+            await connection.execute(statement, {"org": org, "account": account})
+        ).fetchall()
+    carriers = [carrier for carrier in (_open_carrier(sealed, org, row) for row in rows) if carrier]
+    if account is not None and not carriers:
+        raise NotFound(NO_SUCH_ACCOUNT.format(account=account))
+    if not carriers:
+        raise NotFound(NO_CARRIER)
+    if len(carriers) > 1:
+        named = ", ".join(carrier.id for carrier in carriers)
+        raise Conflict(WHICH_ACCOUNT.format(count=len(carriers), accounts=named))
+    return carriers[0]
+
+
+async def put_carrier(
+    pool: Pool, sealed: MultiFernet, org: str, account: TwilioAccount | SipPeer | WhatsappAccount
+) -> Carrier:
+    """Keep the account; bringing it again replaces its secret and keeps its termination."""
+    kept = Carrier(org=org, account=account)
+    was = next(
+        (carrier for carrier in await carriers_of(pool, sealed, org) if carrier.id == kept.id),
+        None,
+    )
+    # The termination stays with the account it was made on: only a Twilio account holds one.
+    if was is not None and was.account.kind == account.kind:
+        kept = replace(kept, outbound=was.outbound)
+    await seal_carrier(pool, sealed, kept)
+    return kept
+
+
+async def drop_carrier(
+    pool: Pool, sealed: MultiFernet, org: str, account: str | None = None
+) -> str:
+    """Forget the account; its numbers stay routed until each is let go."""
+    gone = await carrier_named(pool, sealed, org, account)
+    async with pool.connection() as connection:
+        await connection.execute(DROP_CARRIER, {"org": org, "account": gone.id})
+    return gone.id
+
+
+async def box_twilio(pool: Pool, sealed: MultiFernet) -> TwilioAccount:
+    """The box's own Twilio account, or NotAvailable when it holds none."""
+    carrier = (await vault.box_credentials(pool, sealed)).get(BOX_ACCOUNT)
+    try:
+        return TwilioAccount.model_validate(carrier)
+    except ValidationError:
+        raise NotAvailable(NO_BOX_TWILIO) from None
+
+
+async def seal_carrier(pool: Pool, sealed: MultiFernet, carrier: Carrier) -> None:
+    """Write the account sealed, its termination with it."""
+    secret = _Sealed(account=carrier.account, outbound=carrier.outbound)
+    row = {
+        "org": carrier.org,
+        "kind": carrier.account.kind,
+        "account": carrier.id,
+        "label": carrier.account.label,
+        "ciphertext": vault.sealed(sealed, secret.model_dump(mode="json")),
+    }
+    async with pool.connection() as connection:
+        await connection.execute(PUT_CARRIER, row)
+
+
+def _open_carrier(sealed: MultiFernet, org: str, row: DictRow) -> Carrier | None:
+    secret = vault.opened(sealed, str(row["ciphertext"]))
+    try:
+        kept = _Sealed.model_validate(secret)
+    except ValidationError:
+        logger.warning("org %s's carrier account %s is not one this box reads", org, row["account"])
+        return None
+    return Carrier(org=org, account=kept.account, outbound=kept.outbound)