plimsoll-client 0.19.0__py3-none-any.whl

plimsoll_client/__init__.py

@@ -0,0 +1,116 @@
+"""A Python client for plimsolld, the plimsoll sandbox daemon.
+
+    from plimsoll_client import Client
+
+    c = Client("http://127.0.0.1:8080", token="...")
+    r = c.run_javascript("console.log(6*7)", minimum_isolation="container")
+    print(r.stdout_text, r.isolation, r.record.sha256)
+
+Standard library only. Every answered run's record is recomputed and checked, the
+isolation floor is sent and the answer's tier checked against it, a session's
+chain of records is followed call by call, and refusals come back as typed errors
+that say whether anything ran. See README.md beside this package.
+"""
+
+from ._record import VERSION as RECORD_VERSION
+from ._transport import MAX_RESPONSE_BYTES
+from ._version import __version__
+from .aio import AsyncClient, AsyncSession
+from .client import PROTOCOL, Client, Session
+from .errors import (
+    AtCapacityError,
+    ChainError,
+    DataLossError,
+    DisabledError,
+    InsecureHTTPError,
+    InsufficientIsolationError,
+    InvalidBaseURLError,
+    InvalidOptionError,
+    InvalidRequestError,
+    IsolationEvidenceMismatchError,
+    MalformedResponseError,
+    NoRecordError,
+    PlimsollError,
+    ProtocolMismatchError,
+    RecordMismatchError,
+    RecordVersionError,
+    RequestTimeoutError,
+    ResponseTooLargeError,
+    ResultKindMismatchError,
+    SessionEndedError,
+    SoftwareEvidenceMismatchError,
+    SoftwareMismatchError,
+    TransportError,
+    UnsupportedError,
+)
+from .types import (
+    CellResult,
+    AdviceFinding,
+    Artifact,
+    Info,
+    JavaScriptResult,
+    ModuleResult,
+    ModuleRun,
+    PayloadEnvironment,
+    ProjectResult,
+    Resources,
+    RunEvidence,
+    RunRecord,
+    SessionEnded,
+    SessionSummary,
+    SoftwareRule,
+    StepResult,
+    meets,
+)
+
+__all__ = [
+    "CellResult",
+    "__version__",
+    "PROTOCOL",
+    "RECORD_VERSION",
+    "MAX_RESPONSE_BYTES",
+    "Client",
+    "Session",
+    "AsyncClient",
+    "AsyncSession",
+    "SoftwareRule",
+    "meets",
+    "Info",
+    "PayloadEnvironment",
+    "Resources",
+    "RunEvidence",
+    "RunRecord",
+    "AdviceFinding",
+    "JavaScriptResult",
+    "ProjectResult",
+    "StepResult",
+    "Artifact",
+    "ModuleResult",
+    "ModuleRun",
+    "SessionEnded",
+    "SessionSummary",
+    "PlimsollError",
+    "InvalidBaseURLError",
+    "InvalidOptionError",
+    "InsecureHTTPError",
+    "InvalidRequestError",
+    "InsufficientIsolationError",
+    "SoftwareMismatchError",
+    "DisabledError",
+    "UnsupportedError",
+    "ProtocolMismatchError",
+    "AtCapacityError",
+    "SessionEndedError",
+    "TransportError",
+    "RequestTimeoutError",
+    "ResponseTooLargeError",
+    "MalformedResponseError",
+    "DataLossError",
+    "RecordMismatchError",
+    "NoRecordError",
+    "RecordVersionError",
+    "ChainError",
+    "IsolationEvidenceMismatchError",
+    "SoftwareEvidenceMismatchError",
+    "ResultKindMismatchError",
+]

plimsoll_client/_record.py

@@ -0,0 +1,300 @@
+"""Run-record digests and checks, ported from the Go package ``record``.
+
+Every digest is lowercase hex SHA-256 over a length-prefixed encoding, never over
+protobuf or JSON bytes (docs/run-records.md). The digests here are computed from
+the JSON forms of the messages: the request exactly as this client sends it, the
+response exactly as it was parsed.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import struct
+from typing import Iterable, Optional
+
+from ._wire import INT32, INT64, OUTCOMES, UINT32, UINT64, Msg
+from .errors import IsolationEvidenceMismatchError, NoRecordError, RecordMismatchError, RecordVersionError
+from .types import RunRecord, SoftwareRule, meets
+
+VERSION = 2
+"""The record encoding version this client computes and checks (record.Version)."""
+
+UNANSWERED_VERSION = 3
+"""The record version of a session call that may have run but ended in an error
+(record.UnansweredVersion): version 2's fields, then ``unanswered``."""
+
+_UNANSWERED_CODES = frozenset((
+    "canceled", "unknown", "invalid_argument", "deadline_exceeded", "not_found", "already_exists",
+    "permission_denied", "resource_exhausted", "failed_precondition", "aborted", "out_of_range",
+    "unimplemented", "internal", "unavailable", "data_loss", "unauthenticated",
+))
+
+
+class _Encoder:
+    def __init__(self, domain: str) -> None:
+        self._h = hashlib.sha256()
+        self._value(domain.encode("utf-8"))
+
+    def _value(self, b: bytes) -> None:
+        self._h.update(struct.pack(">Q", len(b)))
+        self._h.update(b)
+
+    def bytes(self, name: str, v: bytes) -> None:
+        self._value(name.encode("utf-8"))
+        self._value(v)
+
+    def str(self, name: str, v: str) -> None:
+        self.bytes(name, v.encode("utf-8"))
+
+    def int(self, name: str, v: int) -> None:
+        self.str(name, "%d" % v)
+
+    def bool(self, name: str, v: bool) -> None:
+        self.str(name, "true" if v else "false")
+
+    def floats(self, name: str, vs: Iterable[float]) -> None:
+        self.bytes(name, b"".join(struct.pack(">d", v) for v in vs))
+
+    def sum(self) -> str:
+        return self._h.hexdigest()
+
+
+def request_digest(req: dict) -> str:
+    """The request digest of a Run request or a session call, from its JSON form.
+    The trace ID and the session ID are left out (record.RunRequestDigest and
+    record.SessionRunRequestDigest)."""
+    m = Msg(req, "request")
+    protocol = m.get_int("protocol", UINT32)
+    e = _Encoder("plimsoll.run-request.v2" if protocol >= 2 else "plimsoll.run-request.v1")
+    e.int("protocol", protocol)
+    e.str("minimum_isolation", m.get_str("minimumIsolation"))
+    e.int("timeout_ms", m.get_int("timeoutMs", INT32))
+    if protocol >= 2:
+        rule = m.get_msg("softwareRule")
+        ids = rule.get_strs("identities") if rule else []
+        e.str("software_mode", rule.get_str("mode") if rule else "")
+        e.int("software_identities", len(ids))
+        for i in ids:
+            e.str("software_identity", i)
+    js, project, module, cell = m.get_msg("javascript"), m.get_msg("project"), m.get_msg("module"), m.get_msg("cell")
+    if js is not None:
+        e.str("kind", "javascript")
+        e.str("code", js.get_str("code"))
+        e.str("grant_profile", js.get_str("grantProfile"))
+    elif cell is not None:
+        e.str("kind", "cell")
+        e.str("language", cell.get_str("language"))
+        e.str("code", cell.get_str("code"))
+        files = cell.get_msgs("files")
+        e.int("files", len(files))
+        for f in files:
+            e.str("file_path", f.get_str("path"))
+            e.str("file_content", f.get_str("content"))
+    elif project is not None:
+        e.str("kind", "project")
+        e.str("grant_profile", project.get_str("grantProfile"))
+        files = project.get_msgs("files")
+        e.int("files", len(files))
+        for f in files:
+            e.str("file_path", f.get_str("path"))
+            e.str("file_content", f.get_str("content"))
+        steps = project.get_strs("steps")
+        e.int("steps", len(steps))
+        for s in steps:
+            e.str("step_command", s)
+        artifacts = project.get_strs("artifacts")
+        e.int("artifacts", len(artifacts))
+        for a in artifacts:
+            e.str("artifact_path", a)
+    elif module is not None:
+        e.str("kind", "module")
+        e.str("model", module.get_str("model"))
+        e.floats("end_time", [module.get_float("endTime")])
+        e.floats("step", [module.get_float("step")])
+        rows = module.get_msgs("rows")
+        e.int("rows", len(rows))
+        for r in rows:
+            e.floats("row_values", r.get_floats("values"))
+    else:
+        e.str("kind", "")
+    return e.sum()
+
+
+def result_digest(resp: Msg) -> str:
+    """The result digest of a RunResponse as received (record.ResultDigest):
+    durations, advice and the evidence fields are left out."""
+    e = _Encoder("plimsoll.run-result.v1")
+    js, project, module, cell = resp.get_msg("javascript"), resp.get_msg("project"), resp.get_msg("module"), resp.get_msg("cell")
+    if cell is not None:
+        e.str("kind", "cell")
+        e.int("exit_code", cell.get_int("exitCode", INT32))
+        e.bool("timed_out", cell.get_bool("timedOut"))
+        e.bytes("stdout", cell.get_bytes("stdout"))
+        e.bytes("stderr", cell.get_bytes("stderr"))
+        e.bool("stdout_truncated", cell.get_bool("stdoutTruncated"))
+        e.bool("stderr_truncated", cell.get_bool("stderrTruncated"))
+        e.bool("interpreter_started", cell.get_bool("interpreterStarted"))
+        e.bool("interpreter_ended", cell.get_bool("interpreterEnded"))
+    elif js is not None:
+        e.str("kind", "javascript")
+        e.int("exit_code", js.get_int("exitCode", INT32))
+        e.bool("timed_out", js.get_bool("timedOut"))
+        e.bytes("stdout", js.get_bytes("stdout"))
+        e.bytes("stderr", js.get_bytes("stderr"))
+        e.bool("stdout_truncated", js.get_bool("stdoutTruncated"))
+        e.bool("stderr_truncated", js.get_bool("stderrTruncated"))
+    elif project is not None:
+        e.str("kind", "project")
+        e.int("outcome", project.get_enum("outcome", OUTCOMES))
+        e.str("outcome_detail", project.get_str("outcomeDetail"))
+        e.bool("artifacts_truncated", project.get_bool("artifactsTruncated"))
+        steps = project.get_msgs("steps")
+        e.int("steps", len(steps))
+        for s in steps:
+            e.str("step_command", s.get_str("command"))
+            e.int("step_exit_code", s.get_int("exitCode", INT32))
+            e.bool("step_timed_out", s.get_bool("timedOut"))
+            e.bytes("step_stdout", s.get_bytes("stdout"))
+            e.bytes("step_stderr", s.get_bytes("stderr"))
+            e.bool("step_stdout_truncated", s.get_bool("stdoutTruncated"))
+            e.bool("step_stderr_truncated", s.get_bool("stderrTruncated"))
+        artifacts = project.get_msgs("artifacts")
+        e.int("artifacts", len(artifacts))
+        for a in artifacts:
+            e.str("artifact_path", a.get_str("path"))
+            e.bytes("artifact_content", a.get_bytes("content"))
+    elif module is not None:
+        e.str("kind", "module")
+        e.int("outcome", module.get_enum("outcome", OUTCOMES))
+        e.str("outcome_detail", module.get_str("outcomeDetail"))
+        e.int("width", module.get_int("width", INT32))
+        e.bytes("stdout", module.get_bytes("stdout"))
+        e.bytes("stderr", module.get_bytes("stderr"))
+        runs = module.get_msgs("runs")
+        e.int("runs", len(runs))
+        for run in runs:
+            e.int("run_status", run.get_int("status", INT32))
+            e.floats("run_outputs", run.get_floats("outputs"))
+    else:
+        e.str("kind", "")
+    return e.sum()
+
+
+def record_digest(r: RunRecord) -> str:
+    """A record's own digest over every field but ``sha256`` (record.Digest). The
+    version is the domain's suffix."""
+    e = _Encoder("plimsoll.run-record.v%d" % r.version)
+    e.str("request_sha256", r.request_sha256)
+    e.str("result_sha256", r.result_sha256)
+    if r.version >= 3:
+        e.str("unanswered", r.unanswered)
+    e.str("provider", r.provider)
+    e.str("isolation", r.isolation)
+    e.str("environment", r.environment)
+    e.str("policy", r.policy)
+    if r.version >= 2:
+        e.str("software_identity", r.software_identity)
+        e.str("software_rule_id", r.software_rule_id)
+    e.int("started_unix_ms", r.started_unix_ms)
+    e.int("ended_unix_ms", r.ended_unix_ms)
+    e.str("session", r.session)
+    e.int("sequence", r.sequence)
+    e.str("previous_sha256", r.previous_sha256)
+    return e.sum()
+
+
+def session_fingerprint(session_id: str) -> str:
+    """The SHA-256 of a session ID, which a session call's record carries instead
+    of the ID (record.SessionFingerprint)."""
+    return hashlib.sha256(session_id.encode("utf-8")).hexdigest()
+
+
+def record_from_wire(m: Msg) -> RunRecord:
+    return RunRecord(
+        version=m.get_int("version", UINT32),
+        request_sha256=m.get_str("requestSha256"),
+        result_sha256=m.get_str("resultSha256"),
+        provider=m.get_str("provider"),
+        isolation=m.get_str("isolation"),
+        environment=m.get_str("environment"),
+        policy=m.get_str("policy"),
+        software_identity=m.get_str("softwareIdentity"),
+        software_rule_id=m.get_str("softwareRuleId"),
+        started_unix_ms=m.get_int("startedUnixMs", INT64),
+        ended_unix_ms=m.get_int("endedUnixMs", INT64),
+        session=m.get_str("session"),
+        sequence=m.get_int("sequence", UINT64),
+        previous_sha256=m.get_str("previousSha256"),
+        sha256=m.get_str("recordSha256"),
+        unanswered=m.get_str("unanswered"),
+    )
+
+
+def check(req_digest: str, protocol: int, rule: Optional[SoftwareRule], resp: Msg) -> RunRecord:
+    """Everything a record states that the caller can recompute (record.check):
+    the version, both digests, the evidence the response repeats, the software
+    rule and the record's own digest. The rule was validated before sending."""
+    rec_msg = resp.get_msg("record")
+    if rec_msg is None:
+        raise NoRecordError("plimsoll: the response carries no run record")
+    r = record_from_wire(rec_msg)
+    result = result_digest(resp)
+    if r.version not in (1, VERSION):
+        raise RecordVersionError(f"plimsoll: unknown run record version {r.version} (this client knows 1 and {VERSION})")
+    if protocol >= 2 and r.version != VERSION:
+        raise RecordVersionError(f"plimsoll: protocol {protocol} requires record version {VERSION}, the record is version {r.version}")
+    if r.version == 1 and (r.software_identity or r.software_rule_id):
+        raise RecordMismatchError("plimsoll: a version 1 record cannot carry software admission fields")
+    if r.unanswered:
+        raise RecordMismatchError(f"plimsoll: an answered call's record states an unanswered code, which version {r.version} does not cover")
+    if r.request_sha256 != req_digest:
+        raise RecordMismatchError(f"plimsoll: request digest {r.request_sha256}, the request sent digests to {req_digest}")
+    if r.result_sha256 != result:
+        raise RecordMismatchError(f"plimsoll: result digest {r.result_sha256}, the result received digests to {result}")
+    if r.provider != resp.get_str("sandbox") or r.isolation != resp.get_str("isolation"):
+        raise RecordMismatchError(
+            f"plimsoll: the record names {r.provider} at {r.isolation!r}, the response {resp.get_str('sandbox')} at {resp.get_str('isolation')!r}"
+        )
+    if r.version >= 2 and r.environment != resp.get_str("environment"):
+        raise RecordMismatchError("plimsoll: the record's environment differs from the response's")
+    if r.version >= 2:
+        rule_id = rule.rule_id() if rule is not None else ""
+        allowed = rule.allows(r.software_identity) if rule is not None else True
+        if r.software_identity != resp.get_str("softwareIdentity") or r.software_rule_id != rule_id or not allowed:
+            raise RecordMismatchError("plimsoll: the selected software or admission rule differs from the request and response")
+    own = record_digest(r)
+    if r.sha256 != own:
+        raise RecordMismatchError(f"plimsoll: record digest {r.sha256}, its fields digest to {own}")
+    return r
+
+
+def check_unanswered(req_digest: str, floor: str, rule: Optional[SoftwareRule], m: Msg) -> RunRecord:
+    """The record an unanswered session call's error carries (record.CheckUnanswered,
+    without the chain, which the Session checks): version 3, no result digest, a
+    Connect code, the digest of the request sent, its software rule and that its
+    software is in it, the record's own digest, and its tier against the call's floor."""
+    r = record_from_wire(m)
+    if r.version != UNANSWERED_VERSION:
+        raise RecordVersionError(f"plimsoll: an unanswered call's record is version {r.version}, not {UNANSWERED_VERSION}")
+    if r.result_sha256 or r.unanswered not in _UNANSWERED_CODES:
+        raise RecordMismatchError("plimsoll: an unanswered call's record states a result or no error code")
+    if r.request_sha256 != req_digest:
+        raise RecordMismatchError(f"plimsoll: request digest {r.request_sha256}, the request sent digests to {req_digest}")
+    if r.software_rule_id != (rule.rule_id() if rule is not None else "") or (rule is not None and not rule.allows(r.software_identity)):
+        raise RecordMismatchError("plimsoll: the record's software rule is not the request's, or its software is not in it")
+    own = record_digest(r)
+    if r.sha256 != own:
+        raise RecordMismatchError(f"plimsoll: record digest {r.sha256}, its fields digest to {own}")
+    if floor and not meets(r.isolation, floor):
+        raise IsolationEvidenceMismatchError(
+            f"plimsoll: the unanswered call's record states {r.isolation or 'unknown'}, below the call's minimum {floor}; execution may have occurred"
+        )
+    return r
+
+
+def check_single(req_digest: str, protocol: int, rule: Optional[SoftwareRule], resp: Msg) -> RunRecord:
+    """check, for a single run: a single run's record carries no session fields (record.Check)."""
+    r = check(req_digest, protocol, rule, resp)
+    if r.session or r.sequence or r.previous_sha256:
+        raise RecordMismatchError("plimsoll: a single run's record carries session fields")
+    return r

plimsoll_client/_transport.py

@@ -0,0 +1,149 @@
+"""One unary Connect call with the JSON codec, over HTTP/1.1.
+
+It uses http.client (the layer urllib.request is built on) directly, for three
+reasons: a redirect is never followed (a Connect call has none, and following one
+would carry the bearer token and the code to another address); proxy settings in
+the environment are not consulted; and the request timeout bounds the whole
+exchange, not each socket read, so a daemon that trickles its answer a byte at a
+time cannot hold the caller past it.
+"""
+
+from __future__ import annotations
+
+import http.client
+import re
+import socket
+import ssl
+import threading
+import time
+from typing import Any, Dict, List, Optional, Tuple
+from urllib.parse import urlsplit
+
+from ._version import __version__
+from ._wire import Msg, dumps, error_from_wire, parse_response
+from .errors import MalformedResponseError, RequestTimeoutError, ResponseTooLargeError, TransportError
+
+SERVICE = "plimsoll.v1.SandboxService"
+
+MAX_RESPONSE_BYTES = 32 << 20
+"""Above the largest legitimate project answer (bounded step output plus the
+aggregate artifact cap), so a misbehaving daemon cannot make the client buffer
+without bound: the Go client's maxResponseBytes."""
+
+_CHUNK = 1 << 16
+
+_DIGITS = re.compile(r"[0-9]+")
+
+
+class Transport:
+    def __init__(self, base_url: str, token: Optional[str], timeout: float, ssl_context: Optional[ssl.SSLContext]) -> None:
+        u = urlsplit(base_url)
+        self._https = u.scheme == "https"
+        self._host = u.hostname or ""
+        self._port = u.port
+        self._prefix = u.path.rstrip("/")
+        self._token = token
+        self._timeout = timeout
+        self._ssl = ssl_context if ssl_context is not None else (ssl.create_default_context() if self._https else None)
+
+    def _connection(self) -> http.client.HTTPConnection:
+        if self._https:
+            return http.client.HTTPSConnection(self._host, self._port, timeout=self._timeout, context=self._ssl)
+        return http.client.HTTPConnection(self._host, self._port, timeout=self._timeout)
+
+    def call(self, method: str, body: Dict[str, Any], path: str) -> Msg:
+        """POSTs body to the procedure and returns the answer as a message. A
+        Connect error answer raises the restored error; anything that is not a
+        Connect answer raises TransportError."""
+        data = dumps(body)
+        headers = {
+            "Content-Type": "application/json",
+            "Connect-Protocol-Version": "1",
+            "Accept-Encoding": "identity",
+            "User-Agent": f"plimsoll-client-python/{__version__}",
+        }
+        if self._token:
+            headers["Authorization"] = f"Bearer {self._token}"
+        deadline = time.monotonic() + self._timeout
+        conn = self._connection()
+        fired = threading.Event()
+        timer: Optional[threading.Timer] = None
+        try:
+            try:
+                conn.connect()
+                # The socket timeout bounds each read; the timer bounds them all,
+                # by shutting the socket down when the deadline passes.
+                timer = threading.Timer(max(deadline - time.monotonic(), 0.0), _abort, (conn, fired))
+                timer.daemon = True
+                timer.start()
+                try:
+                    conn.request("POST", f"{self._prefix}/{SERVICE}/{method}", body=data, headers=headers)
+                except (BrokenPipeError, ConnectionResetError):
+                    # The daemon can answer before the whole body is sent (a refusal
+                    # needs no payload) and close its end; its answer, which may say
+                    # nothing ran, is read below instead of being lost to the write.
+                    if fired.is_set():
+                        raise
+                _settimeout(conn, deadline)
+                resp = conn.getresponse()
+                raw, complete = _read_capped(conn, resp, deadline)
+                # The timer shuts the socket down, which ends a read early: an answer
+                # cut short is a timeout, but one read to its stated end is the answer.
+                if fired.is_set() and not complete:
+                    raise socket.timeout("deadline passed")
+            except (socket.timeout, TimeoutError):
+                raise RequestTimeoutError(f"plimsoll: {method} did not finish within {self._timeout} s") from None
+            except (OSError, http.client.HTTPException) as e:
+                if fired.is_set():
+                    raise RequestTimeoutError(f"plimsoll: {method} did not finish within {self._timeout} s") from None
+                raise TransportError(f"plimsoll: {method}: {e}") from e
+        finally:
+            if timer is not None:
+                timer.cancel()
+            conn.close()
+        if resp.status != 200:
+            raise error_from_wire(resp.status, raw)
+        ctype = (resp.getheader("Content-Type") or "").split(";", 1)[0].strip().lower()
+        if ctype != "application/json":
+            raise MalformedResponseError(f"plimsoll: {method} answered with content type {ctype or 'none'!r}, not application/json")
+        return parse_response(raw, path)
+
+
+def _abort(conn: http.client.HTTPConnection, fired: threading.Event) -> None:
+    fired.set()
+    sock = conn.sock
+    if sock is not None:
+        try:
+            sock.shutdown(socket.SHUT_RDWR)
+        except OSError:
+            pass
+
+
+def _settimeout(conn: http.client.HTTPConnection, deadline: float) -> None:
+    remaining = deadline - time.monotonic()
+    if remaining <= 0:
+        raise socket.timeout("deadline passed")
+    if conn.sock is not None:
+        conn.sock.settimeout(remaining)
+
+
+def _read_capped(conn: http.client.HTTPConnection, resp: http.client.HTTPResponse, deadline: float) -> Tuple[bytes, bool]:
+    """The answer's body, and whether it is known complete: read to the length its
+    Content-Length states."""
+    header = (resp.getheader("Content-Length") or "").strip()
+    # ASCII digits only: str.isdigit() also accepts "²", which int() refuses.
+    length = int(header) if _DIGITS.fullmatch(header) else None
+    if length is not None and length > MAX_RESPONSE_BYTES:
+        raise ResponseTooLargeError(f"plimsoll: the daemon's answer is {length} bytes, over the {MAX_RESPONSE_BYTES} byte limit")
+    chunks: List[bytes] = []
+    n = 0
+    while True:
+        _settimeout(conn, deadline)
+        chunk = resp.read1(_CHUNK)  # one read at most, so the deadline is checked between reads
+        if not chunk:
+            break
+        n += len(chunk)
+        if n > MAX_RESPONSE_BYTES:
+            raise ResponseTooLargeError(f"plimsoll: the daemon's answer exceeds {MAX_RESPONSE_BYTES} bytes")
+        chunks.append(chunk)
+    return b"".join(chunks), length is not None and n == length