pinecall-runtime 0.1.6__py3-none-any.whl

pinecall/process/recordings.py

@@ -0,0 +1,323 @@
+"""Where a call's audio is kept: the disk it was recorded on, or a bucket, under its org."""
+
+import asyncio
+import hashlib
+import shutil
+from collections.abc import AsyncIterator
+from dataclasses import dataclass
+from http import HTTPStatus
+from pathlib import Path, PurePath
+
+import httpx
+
+from pinecall.domain.errors import DeclarationRefused, UpstreamFailed
+from pinecall.process._objects import ObjectStore, object_store_of
+from pinecall.process.sealed_audio import (
+    BROKEN,
+    HEADER,
+    MAGIC,
+    Sealed,
+    Span,
+    opened,
+    recorded_size,
+    span_of,
+)
+from pinecall.process.settings import Settings
+
+# The recorder's file in the call's own directory: `<root>/<call>/audio.ogg` on the disk,
+# `<org>/<call>/audio.ogg` in the bucket. Sealed under the call's own key, it is `audio.sealed`
+# beside it (sealed_audio.py): the name says which a stored recording is.
+AUDIO_FILE = "audio.ogg"
+
+SEALED_FILE = "audio.sealed"
+
+# An hour of a call is tens of megabytes: the default five seconds is a small file's. Under what
+# a job is given to seal (worker/main.py SEALING_S): an upload that hangs leaves the file on the
+# disk and the call is still sealed.
+UPLOAD_TIMEOUT_S = 30.0
+
+# What an upload reads of the file at a time: hashed first, then sent, and never held whole.
+READ_BYTES = 256 * 1024
+
+# What a player needs from the bucket's answer to seek.
+PASSED_ON = ("content-length", "content-range", "accept-ranges")
+
+# The answers a read passes on: the whole file, a range of it, a range past its end.
+SERVED = frozenset({200, 206, 416})
+
+# An org's erasure deletes its calls' objects this many at a time.
+DELETED_AT_ONCE = 16
+
+REFUSED = "the recordings bucket {bucket} answered {status} to {what} {name}: {text}"
+
+UNREACHABLE = "the recordings bucket {bucket} did not answer {what} {name}: {why}"
+
+
+NOT_UNDER_THE_ROOT = "call {call!r} names no directory under the recordings root"
+
+
+@dataclass(frozen=True)
+class Fetched:
+    """A recording read from the bucket: the status and headers to pass on, and its bytes."""
+
+    status: int
+    headers: dict[str, str]
+    body: AsyncIterator[bytes]
+
+
+@dataclass(frozen=True)
+class Disk:
+    """Recordings kept on the disk they were recorded on: a box with no bucket, as always."""
+
+    root: Path
+
+    async def store(self, org: str, call: str, audio: Path) -> None:
+        """Nothing to do: the recorder's file is where it is kept."""
+
+    async def fetch(self, org: str, call: str, byte_range: str | None) -> Fetched | None:
+        """None: the file on the disk is the recording, and the door serves it as a file."""
+
+    async def sealed(self, org: str, call: str) -> Sealed | None:
+        """None: a sealed file on the disk is read from where the call's summary says it is."""
+
+    async def erase(self, org: str, calls: list[str]) -> int:
+        """Remove each call's recording directory; how many calls had one."""
+        return len(await asyncio.to_thread(_removed, self.root, calls))
+
+
+@dataclass(frozen=True)
+class Bucket:
+    """Recordings moved to a bucket of the object store once written, the disk holding one until."""
+
+    root: Path
+    name: str
+    objects: ObjectStore
+
+    async def store(self, org: str, call: str, audio: Path) -> None:
+        """Upload the file under the org, then remove it from the disk; raise if it stayed."""
+        what = _object_name(org, call, audio.name)
+        size, digest = await asyncio.to_thread(_measured, audio)
+        url = self.objects.url_of(self.name, what)
+        kind = "audio/ogg" if audio.name == AUDIO_FILE else "application/octet-stream"
+        wanted = {"content-type": kind, "content-length": str(size)}
+        request = self.objects.http.build_request(
+            "PUT",
+            url,
+            headers=self.objects.signed("PUT", url, wanted, digest),
+            content=_read(audio),
+            timeout=UPLOAD_TIMEOUT_S,
+        )
+        answer = await self._sent(request, "an upload of", what)
+        await answer.aread()
+        await answer.aclose()
+        if answer.status_code != HTTPStatus.OK:
+            raise self._refused("an upload of", what, answer)
+        await asyncio.to_thread(_removed, self.root, [call])
+
+    async def fetch(self, org: str, call: str, byte_range: str | None) -> Fetched | None:
+        """The recording's bytes, the range asked for when one is; None while it is not there."""
+        return await self._fetched(_object_name(org, call, AUDIO_FILE), byte_range)
+
+    async def sealed(self, org: str, call: str) -> Sealed | None:
+        """The call's sealed object, read by ranges; None while it is not in the bucket."""
+        what = _object_name(org, call, SEALED_FILE)
+        first = await self._fetched(what, f"bytes=0-{HEADER - 1}")
+        if first is None:
+            return None
+        header = b"".join([piece async for piece in first.body])
+        size = first.headers.get("content-range", "").rpartition("/")[2]
+        if not header.startswith(MAGIC) or not size.isdigit():
+            raise UpstreamFailed(BROKEN.format(call=call, why=f"{what} is not a sealed recording"))
+
+        async def read(offset: int, length: int) -> AsyncIterator[bytes]:
+            part = await self._fetched(what, f"bytes={offset}-{offset + length - 1}")
+            if part is None:
+                raise UpstreamFailed(BROKEN.format(call=call, why=f"{what} went while it was read"))
+            async for piece in part.body:
+                yield piece
+
+        return Sealed(call, int(size), header[len(MAGIC) :], read)
+
+    async def _fetched(self, what: str, byte_range: str | None) -> Fetched | None:
+        url = self.objects.url_of(self.name, what)
+        wanted = {} if byte_range is None else {"range": byte_range}
+        # The bytes as stored, so the length and the range passed on are the file's own.
+        headers = {**self.objects.signed("GET", url, wanted), "accept-encoding": "identity"}
+        answer = await self._sent(
+            self.objects.http.build_request("GET", url, headers=headers), "a read of", what
+        )
+        if answer.status_code not in SERVED:
+            await answer.aread()
+            await answer.aclose()
+            if answer.status_code == HTTPStatus.NOT_FOUND:
+                return None
+            raise self._refused("a read of", what, answer)
+        kept = {name: answer.headers[name] for name in PASSED_ON if name in answer.headers}
+        return Fetched(answer.status_code, kept, _streamed(answer))
+
+    async def erase(self, org: str, calls: list[str]) -> int:
+        """Delete each call's objects, and its file where one stayed; how many calls had either."""
+        deleted: set[str] = set()
+        for start in range(0, len(calls), DELETED_AT_ONCE):
+            chunk = calls[start : start + DELETED_AT_ONCE]
+            gone = await asyncio.gather(*(self._deleted(org, call) for call in chunk))
+            deleted |= {call for call, was_there in zip(chunk, gone, strict=True) if was_there}
+        return len(deleted | await asyncio.to_thread(_removed, self.root, calls))
+
+    # S3 answers a delete of nothing as it answers a delete: each object is looked for first, so
+    # the trail counts the recordings there were.
+    async def _deleted(self, org: str, call: str) -> bool:
+        kept = [await self._deleted_named(_object_name(org, call, name)) for name in NAMES]
+        return any(kept)
+
+    async def _deleted_named(self, what: str) -> bool:
+        url = self.objects.url_of(self.name, what)
+        existing = await self._response_to("HEAD", url, what)
+        if existing.status_code == HTTPStatus.NOT_FOUND:
+            return False
+        if existing.status_code != HTTPStatus.OK:
+            raise self._refused("a delete of", what, existing)
+        answer = await self._response_to("DELETE", url, what)
+        if answer.status_code not in {HTTPStatus.OK, HTTPStatus.NO_CONTENT}:
+            raise self._refused("a delete of", what, answer)
+        return True
+
+    async def _response_to(self, method: str, url: str, what: str) -> httpx.Response:
+        request = self.objects.http.build_request(
+            method, url, headers=self.objects.signed(method, url, {})
+        )
+        answer = await self._sent(request, "a delete of", what)
+        await answer.aread()
+        await answer.aclose()
+        return answer
+
+    async def _sent(self, request: httpx.Request, what: str, name: str) -> httpx.Response:
+        try:
+            return await self.objects.http.send(request, stream=True)
+        except httpx.HTTPError as unreachable:
+            raise UpstreamFailed(
+                UNREACHABLE.format(
+                    bucket=self.name,
+                    what=what,
+                    name=name,
+                    why=str(unreachable) or type(unreachable).__name__,
+                )
+            ) from unreachable
+
+    def _refused(self, what: str, name: str, answer: httpx.Response) -> UpstreamFailed:
+        return UpstreamFailed(
+            REFUSED.format(
+                bucket=self.name,
+                status=answer.status_code,
+                what=what,
+                name=name,
+                text=answer.text[:200],
+            )
+        )
+
+
+# Every object a call's recording may be kept as.
+NAMES = (AUDIO_FILE, SEALED_FILE)
+
+
+type Recordings = Disk | Bucket
+
+
+def recordings_of(settings: Settings, http: httpx.AsyncClient) -> Recordings:
+    """The bucket PINECALL_RECORDINGS_BUCKET names in the object store, else the disk."""
+    root = Path(settings.recordings_root)
+    objects = object_store_of(settings, http)
+    if settings.recordings_bucket is None or objects is None:
+        return Disk(root)
+    return Bucket(root, settings.recordings_bucket, objects)
+
+
+# The worker's pointer says which file it kept, never where: a summary that named any path would
+# have the gateway serve any file its own disk holds.
+def call_directory(root: Path, call: str) -> Path | None:
+    """The call's directory under the root; None for an id that would name a path outside it."""
+    directory = (root / call).resolve()
+    if directory == root.resolve() or not directory.is_relative_to(root.resolve()):
+        return None
+    return directory
+
+
+# Where the worker's session writes the call's audio: the one place a call's file is named.
+def recording_path(root: Path, call: str) -> Path:
+    """The call's audio file, in a directory of its own under the root; refused outside it."""
+    directory = call_directory(root, call)
+    if directory is None:
+        raise DeclarationRefused(NOT_UNDER_THE_ROOT.format(call=call))
+    directory.mkdir(parents=True, exist_ok=True)
+    return directory / AUDIO_FILE
+
+
+def kept_on_disk(root: Path, call: str, pointer: str) -> Path | None:
+    """The call's recording under the root, by the name its summary gave; None for any other."""
+    name = PurePath(pointer).name
+    path = (root / call / name).resolve()
+    if name not in NAMES or not path.is_relative_to(root.resolve()):
+        return None
+    return path
+
+
+def served_sealed(sealed: Sealed, key: bytes, byte_range: str | None) -> Fetched:
+    """A sealed recording as a player reads it: the range it asked for, or the whole, opened."""
+    size = recorded_size(sealed.size)
+    span = span_of(byte_range, size)
+    if span is not None and span.first >= size:
+        return Fetched(
+            HTTPStatus.REQUESTED_RANGE_NOT_SATISFIABLE,
+            {"content-range": f"bytes */{size}"},
+            _nothing(),
+        )
+    whole = span or Span(0, size - 1)
+    body = opened(sealed, key, whole) if size else _nothing()
+    headers = {"accept-ranges": "bytes", "content-length": str(whole.length)}
+    if span is None:
+        return Fetched(HTTPStatus.OK, headers, body)
+    shown = {**headers, "content-range": f"bytes {span.first}-{span.last}/{size}"}
+    return Fetched(HTTPStatus.PARTIAL_CONTENT, shown, body)
+
+
+def _object_name(org: str, call: str, name: str) -> str:
+    return f"{org}/{call}/{name}"
+
+
+def _measured(audio: Path) -> tuple[int, str]:
+    digest = hashlib.sha256()
+    with audio.open("rb") as source:
+        while chunk := source.read(READ_BYTES):
+            digest.update(chunk)
+    return audio.stat().st_size, digest.hexdigest()
+
+
+async def _read(audio: Path) -> AsyncIterator[bytes]:
+    with audio.open("rb") as source:
+        while chunk := await asyncio.to_thread(source.read, READ_BYTES):
+            yield chunk
+
+
+async def _nothing() -> AsyncIterator[bytes]:
+    for piece in ():
+        yield piece
+
+
+async def _streamed(answer: httpx.Response) -> AsyncIterator[bytes]:
+    try:
+        async for chunk in answer.aiter_bytes():
+            yield chunk
+    finally:
+        await answer.aclose()
+
+
+# A recording is a directory named for its call (recording_path): one under
+# the root, whatever the id says, or nothing is removed.
+def _removed(root: Path, calls: list[str]) -> set[str]:
+    removed: set[str] = set()
+    for call in calls:
+        directory = call_directory(root, call)
+        if directory is not None and directory.is_dir():
+            shutil.rmtree(directory)
+            removed.add(call)
+    return removed

pinecall/process/resolver.py

@@ -0,0 +1,41 @@
+"""What a name resolves to: every address, so a caller can hold them all to the public internet."""
+
+import ipaddress
+import socket
+
+import dns.exception
+import dns.rdatatype
+import dns.rdtypes.ANY.TXT
+import dns.resolver
+
+type Address = ipaddress.IPv4Address | ipaddress.IPv6Address
+
+
+# A TXT lookup waits this long in all, over every nameserver tried.
+TXT_WITHIN_S = 5.0
+
+
+def addresses_of(host: str) -> list[Address]:
+    """Every address the name resolves to; OSError when it resolves to none."""
+    found = socket.getaddrinfo(host, None, type=socket.SOCK_STREAM)
+    return [ipaddress.ip_address(str(item[4][0]).partition("%")[0]) for item in found]
+
+
+def all_public(addresses: list[Address]) -> bool:
+    """Whether there is an address and every one is on the public internet."""
+    return bool(addresses) and all(address.is_global for address in addresses)
+
+
+# A record of several strings is one text, as the RFC reads it; a name with no TXT, or none at all,
+# is an empty list, like one whose nameservers did not answer in time.
+def txt_of(name: str) -> list[str]:
+    """Every TXT record at the name, each as one string; none when there is none or no answer."""
+    try:
+        answer = dns.resolver.resolve(name, dns.rdatatype.TXT, lifetime=TXT_WITHIN_S)
+    except dns.exception.DNSException:
+        return []
+    return [
+        b"".join(rdata.strings).decode("utf-8", errors="replace")
+        for rdata in answer
+        if isinstance(rdata, dns.rdtypes.ANY.TXT.TXT)
+    ]

pinecall/process/sealed_audio.py

@@ -0,0 +1,173 @@
+"""A recording sealed under its own key: AES-GCM a chunk at a time, so a range opens on its own."""
+
+import asyncio
+import os
+from collections.abc import AsyncIterator, Callable
+from dataclasses import dataclass
+from pathlib import Path
+
+from cryptography.exceptions import InvalidTag
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+from pinecall.domain.errors import UpstreamFailed
+
+# What a sealed file starts with, then the 8 random bytes every chunk's nonce begins with.
+MAGIC = b"PCSEAL1\n"
+
+PREFIX_BYTES = 8
+
+# A chunk of the recording as recorded: a range opens the chunks it covers and no other, and a
+# read holds one at a time. 64 KiB is some seconds of a call's audio.
+CHUNK = 64 * 1024
+
+TAG = 16
+
+# The last chunk is sealed as the last, so a file cut short never opens as a shorter recording.
+LAST, MORE = b"\x01", b"\x00"
+
+KEY_BITS = 256
+
+BROKEN = "the sealed recording of {call} does not open: {why}"
+
+# Reads `length` bytes of the sealed object from `offset`, in whatever pieces its source yields.
+type Read = Callable[[int, int], AsyncIterator[bytes]]
+
+
+@dataclass(frozen=True)
+class Sealed:
+    """A sealed recording where it is kept: its size as kept, its nonces' prefix, its reader."""
+
+    call: str
+    size: int
+    prefix: bytes
+    read: Read
+
+
+@dataclass(frozen=True)
+class Span:
+    """The bytes of the recording as recorded that a reader asked for, first and last included."""
+
+    first: int
+    last: int
+
+    @property
+    def length(self) -> int:
+        """How many bytes the span holds."""
+        return self.last - self.first + 1
+
+
+# The format's name and the nonces' prefix, then each chunk and its tag.
+HEADER = len(MAGIC) + PREFIX_BYTES
+
+SEALED_CHUNK = CHUNK + TAG
+
+
+def new_key() -> bytes:
+    """A recording's own key."""
+    return AESGCM.generate_key(bit_length=KEY_BITS)
+
+
+# Blocking, for a thread: the file is read and written a chunk at a time, never whole.
+def seal_file(plain: Path, sealed: Path, key: bytes) -> None:
+    """Write `sealed` from `plain` under the key, then remove `plain`."""
+    cipher = AESGCM(key)
+    prefix = os.urandom(PREFIX_BYTES)
+    part = sealed.with_name(f"{sealed.name}.part")
+    with plain.open("rb") as source, part.open("wb") as target:
+        target.write(MAGIC + prefix)
+        chunk, index = source.read(CHUNK), 0
+        while True:
+            following = source.read(CHUNK)
+            flag = MORE if following else LAST
+            target.write(cipher.encrypt(_nonce(prefix, index), chunk, flag))
+            if not following:
+                break
+            chunk, index = following, index + 1
+        target.flush()
+        os.fsync(target.fileno())
+    part.rename(sealed)
+    plain.unlink()
+
+
+def recorded_size(sealed_size: int) -> int:
+    """How many bytes the recording had, from its sealed object's size."""
+    full, rest = divmod(sealed_size - HEADER, SEALED_CHUNK)
+    return full * CHUNK + max(rest - TAG, 0)
+
+
+def span_of(byte_range: str | None, size: int) -> Span | None:
+    """The one range a player asked for within the recording; None for the whole of it."""
+    if byte_range is None or not byte_range.startswith("bytes=") or "," in byte_range:
+        return None
+    first, _, last = byte_range.removeprefix("bytes=").strip().partition("-")
+    if not (first or last) or not all(bound.isdigit() for bound in (first, last) if bound):
+        return None
+    if not first:
+        return Span(max(size - int(last), 0), size - 1)
+    # A range that ends before it starts is no range: the whole is answered, as HTTP says.
+    if last and int(last) < int(first):
+        return None
+    return Span(int(first), min(int(last), size - 1) if last else size - 1)
+
+
+async def opened(sealed: Sealed, key: bytes, span: Span) -> AsyncIterator[bytes]:
+    """The span's bytes as recorded, opening only the chunks it covers, one at a time."""
+    chunks = -(-(sealed.size - HEADER) // SEALED_CHUNK)
+    first, last = span.first // CHUNK, span.last // CHUNK
+    start = HEADER + first * SEALED_CHUNK
+    end = min(HEADER + (last + 1) * SEALED_CHUNK, sealed.size)
+    cipher = AESGCM(key)
+    index = first
+    async for piece in _in_chunks(sealed.read(start, end - start)):
+        flag = LAST if index == chunks - 1 else MORE
+        try:
+            plain = cipher.decrypt(_nonce(sealed.prefix, index), piece, flag)
+        except InvalidTag:
+            raise UpstreamFailed(BROKEN.format(call=sealed.call, why=f"chunk {index}")) from None
+        low = span.first - index * CHUNK if index == first else 0
+        high = span.last - index * CHUNK + 1 if index == last else len(plain)
+        yield plain[low:high]
+        index += 1
+
+
+async def on_disk(call: str, path: Path) -> Sealed | None:
+    """The sealed file at the path, read a chunk at a time off the loop; None when absent."""
+    try:
+        header, size = await asyncio.to_thread(_head_of, path)
+    except FileNotFoundError:
+        return None
+    if not header.startswith(MAGIC):
+        raise UpstreamFailed(BROKEN.format(call=call, why=f"{path} is not a sealed recording"))
+
+    async def read(offset: int, length: int) -> AsyncIterator[bytes]:
+        with await asyncio.to_thread(path.open, "rb") as file:
+            await asyncio.to_thread(file.seek, offset)
+            left = length
+            while left > 0:
+                piece = await asyncio.to_thread(file.read, min(SEALED_CHUNK, left))
+                if not piece:
+                    return
+                left -= len(piece)
+                yield piece
+
+    return Sealed(call, size, header[len(MAGIC) :], read)
+
+
+def _head_of(path: Path) -> tuple[bytes, int]:
+    with path.open("rb") as file:
+        return file.read(HEADER), path.stat().st_size
+
+
+def _nonce(prefix: bytes, index: int) -> bytes:
+    return prefix + index.to_bytes(4, "big")
+
+
+async def _in_chunks(pieces: AsyncIterator[bytes]) -> AsyncIterator[bytes]:
+    waiting = bytearray()
+    async for piece in pieces:
+        waiting += piece
+        while len(waiting) >= SEALED_CHUNK:
+            yield bytes(waiting[:SEALED_CHUNK])
+            del waiting[:SEALED_CHUNK]
+    if waiting:
+        yield bytes(waiting)