pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/tenancy/codes.py

@@ -0,0 +1,196 @@
+"""The four-digit codes a caller keys to tie their call to a browser page, issued per agent."""
+
+import asyncio
+import contextlib
+import secrets
+import time
+from dataclasses import dataclass
+
+from psycopg.errors import UniqueViolation
+from psycopg.rows import DictRow
+
+from pinecall.domain.errors import NotAvailable, QuotaExhausted
+from pinecall.domain.names import Env
+from pinecall.log.logs import Logs
+from pinecall.postgres.pool import Pool
+from pinecall.wire.events import CodeClaimed, CodeIssued
+from pinecall.wire.parts import Projection
+
+CLAIMED = "code.claimed"
+
+
+TOO_MANY = (
+    "agent {agent} already has {live} codes waiting for a call: let one be claimed or expire "
+    "before issuing another"
+)
+
+
+# Four digits to key on a phone; the cap per agent stops a page minting them by the thousand.
+DIGITS = 4
+
+
+ISSUED = "code.issued"
+
+
+LIVE_PER_AGENT = 50
+
+# A call keys three codes at most: past them a code it keys ties it to no page, answered as one
+# nobody issued, so a caller keying at random learns nothing and has three chances in all.
+TRIES_PER_CALL = 3
+
+A_DAY_S = 24 * 60 * 60.0
+
+# Where a claim wakes the page waiting on the code, whichever gateway it waits on.
+TAKEN_CHANNEL = "code:{agent}:{code}"
+
+# Expired codes leave with the one statement that finds them: two gateways never close one twice.
+EXPIRED = """
+delete from caller_codes where agent = %(agent)s and expires_at <= %(now)s
+returning code, claimed
+"""
+
+LIVE = "select count(*) as live from caller_codes where agent = %(agent)s"
+
+KEPT = """
+insert into caller_codes (agent, code, env, log, expires_at)
+values (%(agent)s, %(code)s, %(env)s, %(log)s, %(expires_at)s)
+"""
+
+FOUND = """
+select agent, code, env, log, expires_at, claimed from caller_codes
+where agent = %(agent)s and code = %(code)s
+"""
+
+# Each try counted in one statement, so two gateways serving one call count both.
+TRIED = """
+insert into code_tries (call, tries, first_at) values (%(call)s, 1, %(now)s)
+on conflict (call) do update set tries = code_tries.tries + 1
+returning tries
+"""
+
+TRIES_GONE = "delete from code_tries where first_at <= %(since)s"
+
+# Taken by one call: the second finds it claimed and gets nothing.
+TAKEN = """
+update caller_codes set claimed = %(call)s
+where agent = %(agent)s and code = %(code)s and env = %(env)s and claimed is null
+  and expires_at > %(now)s
+returning agent, code, env, log, expires_at, claimed
+"""
+
+
+@dataclass(frozen=True)
+class IssuedCode:
+    """A code a page shows, waiting for the call that keys it, and the call once one did."""
+
+    code: str
+    env: Env
+    agent: str
+    expires_at: float
+    log: Projection
+    claimed: str | None = None
+
+
+# Kept in Postgres, so any gateway issues, claims and answers a code; written on each agent's log
+# as code.issued and code.claimed (no call: it expired). A code is the agent's, whatever the world.
+class Codes:
+    """Every agent's live caller codes, and a waiting page's wake-up for each."""
+
+    def __init__(self, logs: Logs) -> None:
+        """Codes kept in the logs' store, their wake-ups on the logs' signal."""
+        self.logs = logs
+        self.pool: Pool = logs.store.pool
+
+    async def issue(self, env: Env, agent: str, ttl_s: float, log: Projection) -> IssuedCode:
+        """A new code for the agent, written on its log; at most fifty live at once."""
+        await self._swept(agent, time.time())
+        async with self.pool.connection() as connection:
+            row = await (await connection.execute(LIVE, {"agent": agent})).fetchone()
+        live = 0 if row is None else int(row["live"])
+        if live >= LIVE_PER_AGENT:
+            raise QuotaExhausted(TOO_MANY.format(agent=agent, live=live))
+        issued = await self._kept(env, agent, time.time() + ttl_s, log)
+        data = CodeIssued(code=issued.code, env=env, expires_at=issued.expires_at, log=log)
+        await self.logs.agent(agent).append(ISSUED, data.written())
+        return issued
+
+    async def status_of(self, env: Env, agent: str, code: str) -> IssuedCode | None:
+        """The code as it stands, once more after it expired; None for one nobody issued."""
+        issued = await self._found(agent, code)
+        await self._swept(agent, time.time())
+        return issued if issued is not None and issued.env == env else None
+
+    # Listened for before the code is read again, so a claim between the two still wakes it.
+    async def waited(self, issued: IssuedCode, within_s: float) -> IssuedCode:
+        """Wait up to that long for a call to key the code, and say how it stands."""
+        channel = TAKEN_CHANNEL.format(agent=issued.agent, code=issued.code)
+        if within_s > 0:
+            with contextlib.suppress(NotAvailable):
+                taken = await self.logs.relay.signal.subscribe(channel)
+                try:
+                    now = await self._found(issued.agent, issued.code)
+                    if now is not None and now.claimed is None:
+                        with contextlib.suppress(TimeoutError, StopAsyncIteration):
+                            await asyncio.wait_for(anext(taken), within_s)
+                finally:
+                    taken.close()
+        return await self._found(issued.agent, issued.code) or issued
+
+    async def claim(self, env: Env, agent: str, code: str, call: str) -> IssuedCode | None:
+        """Tie the code to the call that keyed it; None if nobody's, dead, taken, or a 4th try."""
+        await self._swept(agent, time.time())
+        now = time.time()
+        wanted = {"agent": agent, "code": code, "env": env, "call": call, "now": now}
+        # independent: a sweep of old counts, a try counted (a try refused stays counted), the take
+        async with self.pool.connection() as connection:
+            await connection.execute(TRIES_GONE, {"since": now - A_DAY_S})
+            tried = await (await connection.execute(TRIED, wanted)).fetchone()
+            if tried is None or int(tried["tries"]) > TRIES_PER_CALL:
+                return None
+            row = await (await connection.execute(TAKEN, wanted)).fetchone()
+        if row is None:
+            return None
+        await self.logs.agent(agent).append(CLAIMED, CodeClaimed(code=code, call=call).written())
+        self.logs.relay.signal.publish(TAKEN_CHANNEL.format(agent=agent, code=code), b"taken")
+        return _issued(row)
+
+    async def _kept(self, env: Env, agent: str, expires_at: float, log: Projection) -> IssuedCode:
+        while True:
+            issued = IssuedCode(_drawn(), env, agent, expires_at, log)
+            row = {"agent": agent, "code": issued.code, "env": env, "log": log}
+            try:
+                async with self.pool.connection() as connection:
+                    await connection.execute(KEPT, {**row, "expires_at": expires_at})
+            except UniqueViolation:
+                continue
+            return issued
+
+    async def _found(self, agent: str, code: str) -> IssuedCode | None:
+        async with self.pool.connection() as connection:
+            row = await (await connection.execute(FOUND, {"agent": agent, "code": code})).fetchone()
+        return None if row is None else _issued(row)
+
+    # Swept as codes are asked for, not by a loop of its own.
+    async def _swept(self, agent: str, now: float) -> None:
+        async with self.pool.connection() as connection:
+            expired = await connection.execute(EXPIRED, {"agent": agent, "now": now})
+            rows = await expired.fetchall()
+        for row in rows:
+            if row["claimed"] is None:
+                closed = CodeClaimed(code=str(row["code"]), call=None).written()
+                await self.logs.agent(agent).append(CLAIMED, closed)
+
+
+def _issued(row: DictRow) -> IssuedCode:
+    return IssuedCode(
+        code=str(row["code"]),
+        env="sandbox" if row["env"] == "sandbox" else "production",
+        agent=str(row["agent"]),
+        expires_at=float(row["expires_at"]),
+        log="tenant" if row["log"] == "tenant" else "public",
+        claimed=row["claimed"],
+    )
+
+
+def _drawn() -> str:
+    return f"{secrets.randbelow(10**DIGITS):0{DIGITS}d}"

pinecall/tenancy/consents.py

@@ -0,0 +1,167 @@
+"""Consent and the do-not-call list: facts about a number, never changed, the newest standing."""
+
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Literal
+
+from psycopg.rows import DictRow
+
+from pinecall.domain.errors import DeclarationRefused
+from pinecall.domain.names import parse_e164
+from pinecall.domain.scope import Scope
+from pinecall.postgres.pool import Pool
+from pinecall.wire.rest.numbers import ConsentHistory, ConsentKind, ConsentRow, DoNotCall, OptedOut
+
+type Standing = Literal["consented", "opted_out", "unknown"]
+
+GIVE = """
+INSERT INTO contact_consents (org, env, number, kind, source, text, evidence, given_by, call)
+VALUES (%(org)s, %(env)s, %(number)s, %(kind)s, %(source)s, %(text)s, %(evidence)s,
+        %(given_by)s, %(call)s)
+"""
+
+HISTORY = """
+SELECT kind, source, text, evidence, given_by, call, given_at FROM contact_consents
+WHERE org = %(org)s AND env = %(env)s AND number = %(number)s
+ORDER BY given_at DESC, id DESC
+"""
+
+NEWEST = """
+SELECT kind FROM contact_consents
+WHERE org = %(org)s AND env = %(env)s AND number = %(number)s
+ORDER BY given_at DESC, id DESC LIMIT 1
+"""
+
+# The numbers whose newest row is an opt-out, newest row first, after the row id a page ended on.
+OPTED_OUT = """
+SELECT id, number, given_at, source, given_by FROM (
+    SELECT DISTINCT ON (number) number, kind, given_at, source, given_by, id
+    FROM contact_consents WHERE org = %(org)s AND env = %(env)s
+    ORDER BY number, given_at DESC, id DESC
+) newest
+WHERE kind = 'opt_out' AND (%(after)s::bigint IS NULL OR id < %(after)s)
+ORDER BY id DESC
+LIMIT %(limit)s
+"""
+
+OPTED_OUT_ON = """
+SELECT EXISTS (SELECT 1 FROM contact_consents WHERE call = %(call)s AND kind = 'opt_out') AS opted
+"""
+
+NOT_A_CURSOR = "{after} is no cursor of this list: the last page said it"
+
+A_PAGE = 200
+
+
+@dataclass(frozen=True)
+class Given:
+    """A fact about a number, as it is written down."""
+
+    kind: ConsentKind
+    source: str
+    given_by: str
+    text: str | None = None
+    evidence: str | None = None
+    call: str | None = None
+
+
+async def give(pool: Pool, scope: Scope, number: str, given: Given) -> None:
+    """Write one fact about the number in the scope's world."""
+    params = {"org": scope.org, "env": scope.env, "number": parse_e164(number), **vars(given)}
+    async with pool.connection() as connection:
+        await connection.execute(GIVE, params)
+
+
+async def standing_of(pool: Pool, scope: Scope, number: str) -> Standing:
+    """What stands for the number: its newest row's, or unknown when there is none."""
+    params = {"org": scope.org, "env": scope.env, "number": number.strip()}
+    async with pool.connection() as connection:
+        row = await (await connection.execute(NEWEST, params)).fetchone()
+    return _as_standing(None if row is None else str(row["kind"]))
+
+
+async def history(pool: Pool, scope: Scope, number: str) -> ConsentHistory:
+    """Every fact about the number, newest first, and what stands."""
+    kept = parse_e164(number)
+    params = {"org": scope.org, "env": scope.env, "number": kept}
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(HISTORY, params)).fetchall()
+    listed = [_row(row) for row in rows]
+    return ConsentHistory(
+        number=kept,
+        standing=_as_standing(listed[0].kind if listed else None),
+        rows=listed,
+    )
+
+
+async def do_not_call(
+    pool: Pool, scope: Scope, *, after: str | None = None, limit: int = A_PAGE
+) -> DoNotCall:
+    """The world's do-not-call list, newest first, a page after the cursor."""
+    params = {"org": scope.org, "env": scope.env, "after": _cursor(after), "limit": limit}
+    async with pool.connection() as connection:
+        rows = await (await connection.execute(OPTED_OUT, params)).fetchall()
+    numbers = [
+        OptedOut(
+            number=str(row["number"]),
+            since=_epoch(row["given_at"]),
+            source=str(row["source"]),
+            given_by=str(row["given_by"]),
+        )
+        for row in rows
+    ]
+    last = rows[-1] if len(rows) == limit else None
+    return DoNotCall(numbers=numbers, next=None if last is None else str(last["id"]))
+
+
+async def opted_out_on(pool: Pool, call: str) -> bool:
+    """Whether a number went on the do-not-call list on this call."""
+    async with pool.connection() as connection:
+        row = await (await connection.execute(OPTED_OUT_ON, {"call": call})).fetchone()
+    return row is not None and bool(row["opted"])
+
+
+async def opt_out_many(
+    pool: Pool, scope: Scope, numbers: list[str], given: Given
+) -> tuple[int, list[str]]:
+    """Put every number that is one on the list, in one transaction; how many, and the refused."""
+    kept: list[str] = []
+    refused: list[str] = []
+    for number in numbers:
+        try:
+            kept.append(parse_e164(number))
+        except DeclarationRefused:
+            refused.append(number)
+    rows = [
+        {"org": scope.org, "env": scope.env, "number": number, **vars(given)} for number in kept
+    ]
+    async with (
+        pool.connection() as connection,
+        connection.transaction(),
+        connection.cursor() as cursor,
+    ):
+        await cursor.executemany(GIVE, rows)
+    return len(kept), refused
+
+
+def _as_standing(kind: str | None) -> Standing:
+    if kind is None:
+        return "unknown"
+    return "opted_out" if kind == "opt_out" else "consented"
+
+
+def _row(row: DictRow) -> ConsentRow:
+    return ConsentRow.model_validate({**row, "given_at": _epoch(row["given_at"])})
+
+
+def _epoch(at: datetime) -> float:
+    return at.timestamp()
+
+
+def _cursor(after: str | None) -> int | None:
+    if after is None:
+        return None
+    try:
+        return int(after)
+    except ValueError:
+        raise DeclarationRefused(NOT_A_CURSOR.format(after=after)) from None