150 lines
4.7 KiB
Python
150 lines
4.7 KiB
Python
"""Version 1 of the WeKnora extension protocol, as the Go package pluginapi
|
|
defines it: constants, errors, request signatures and the handshake line."""
|
|
|
|
from __future__ import annotations
|
|
|
|
import hashlib
|
|
import hmac
|
|
import time
|
|
from enum import Enum
|
|
from typing import Dict, Optional
|
|
|
|
PROTOCOL_VERSION = "1"
|
|
API_VERSION = "weknora.plugin/v1"
|
|
|
|
PROTOCOL_HEADER = "X-WeKnora-Protocol"
|
|
REQUEST_ID_HEADER = "X-Request-Id"
|
|
SIGNATURE_HEADER = "X-WeKnora-Signature"
|
|
TIMESTAMP_HEADER = "X-WeKnora-Timestamp"
|
|
NDJSON_CONTENT_TYPE = "application/x-ndjson"
|
|
|
|
# Environment a host plugin is started with.
|
|
ENV_SOCKET = "WEKNORA_PLUGIN_SOCKET"
|
|
ENV_NETWORK = "WEKNORA_PLUGIN_NETWORK"
|
|
ENV_TOKEN = "WEKNORA_PLUGIN_TOKEN"
|
|
ENV_PLUGIN_ID = "WEKNORA_PLUGIN_ID"
|
|
ENV_PLUGIN_VERSION = "WEKNORA_PLUGIN_VERSION"
|
|
# Environment of a remote plugin.
|
|
ENV_ADDR = "WEKNORA_PLUGIN_ADDR"
|
|
ENV_SECRET = "WEKNORA_PLUGIN_SECRET"
|
|
|
|
# How old a signed request may be, in seconds.
|
|
MAX_CLOCK_SKEW = 5 * 60
|
|
|
|
HOST_KV_PATH = "/api/v1/plugin-host/kv"
|
|
HOST_KV_LIST_PATH = "/api/v1/plugin-host/kv/list"
|
|
|
|
|
|
class ErrorCode(str, Enum):
|
|
"""Classifies a failed call; WeKnora reacts to each differently."""
|
|
|
|
INVALID_CONFIG = "invalid_config"
|
|
UNAUTHORIZED = "unauthorized"
|
|
NOT_FOUND = "not_found"
|
|
RATE_LIMITED = "rate_limited"
|
|
UNAVAILABLE = "unavailable"
|
|
BAD_REQUEST = "bad_request"
|
|
INTERNAL = "internal"
|
|
|
|
@property
|
|
def http_status(self) -> int:
|
|
return _STATUS.get(self, 500)
|
|
|
|
|
|
_STATUS = {
|
|
ErrorCode.INVALID_CONFIG: 400,
|
|
ErrorCode.BAD_REQUEST: 400,
|
|
ErrorCode.UNAUTHORIZED: 401,
|
|
ErrorCode.NOT_FOUND: 404,
|
|
ErrorCode.RATE_LIMITED: 429,
|
|
ErrorCode.UNAVAILABLE: 503,
|
|
}
|
|
|
|
|
|
class PluginError(Exception):
|
|
"""A failed call. Raise it to choose the code WeKnora sees; any other
|
|
exception becomes ``internal``. Unavailable and rate-limited errors are
|
|
retryable unless told otherwise."""
|
|
|
|
def __init__(
|
|
self,
|
|
code: ErrorCode | str,
|
|
message: str,
|
|
*,
|
|
retryable: Optional[bool] = None,
|
|
fields: Optional[Dict[str, str]] = None,
|
|
retry_after: int = 0,
|
|
) -> None:
|
|
super().__init__(message)
|
|
try:
|
|
self.code = ErrorCode(code)
|
|
except ValueError:
|
|
self.code = ErrorCode.INTERNAL
|
|
self.message = message
|
|
if retryable is None:
|
|
retryable = self.code in (ErrorCode.UNAVAILABLE, ErrorCode.RATE_LIMITED)
|
|
self.retryable = retryable
|
|
self.fields = fields or {}
|
|
self.retry_after = retry_after
|
|
|
|
def __str__(self) -> str:
|
|
return f"{self.code.value}: {self.message}"
|
|
|
|
def to_wire(self) -> dict:
|
|
out: dict = {"code": self.code.value, "message": self.message}
|
|
if self.retryable:
|
|
out["retryable"] = True
|
|
details: dict = {}
|
|
if self.fields:
|
|
details["fields"] = dict(self.fields)
|
|
if self.retry_after:
|
|
details["retryAfter"] = self.retry_after
|
|
if details:
|
|
out["details"] = details
|
|
return out
|
|
|
|
@classmethod
|
|
def from_wire(cls, body: dict) -> "PluginError":
|
|
details = body.get("details") or {}
|
|
return cls(
|
|
body.get("code") or ErrorCode.INTERNAL,
|
|
body.get("message") or "",
|
|
retryable=bool(body.get("retryable")),
|
|
fields=details.get("fields"),
|
|
retry_after=int(details.get("retryAfter") or 0),
|
|
)
|
|
|
|
|
|
def invalid_config(message: str, fields: Dict[str, str]) -> PluginError:
|
|
"""Reports configuration problems keyed by dotted field path; WeKnora
|
|
shows them on the form."""
|
|
return PluginError(ErrorCode.INVALID_CONFIG, message, fields=fields)
|
|
|
|
|
|
def sign(secret: bytes, timestamp: int, body: bytes) -> str:
|
|
"""The signature of a request body at a unix timestamp: hex HMAC-SHA256
|
|
over ``"<timestamp>.<body>"``."""
|
|
mac = hmac.new(secret, f"{timestamp}.".encode(), hashlib.sha256)
|
|
mac.update(body)
|
|
return mac.hexdigest()
|
|
|
|
|
|
def verify_signature(
|
|
secret: bytes, timestamp: str, signature: str, body: bytes, now: Optional[float] = None
|
|
) -> None:
|
|
"""Checks a signed request; raises ValueError when it does not hold."""
|
|
try:
|
|
ts = int(timestamp)
|
|
except (TypeError, ValueError):
|
|
raise ValueError(f"bad {TIMESTAMP_HEADER}") from None
|
|
now = time.time() if now is None else now
|
|
if abs(now - ts) > MAX_CLOCK_SKEW:
|
|
raise ValueError("request timestamp is outside the allowed clock skew")
|
|
if not hmac.compare_digest(sign(secret, ts, body), signature or ""):
|
|
raise ValueError("bad signature")
|
|
|
|
|
|
def handshake_line(network: str, address: str) -> str:
|
|
"""The line a host plugin prints on stdout once it is ready."""
|
|
return "|".join(["WEKNORA_PLUGIN", PROTOCOL_VERSION, network, address])
|