pickle-strategy-sdk 0.5.0__py3-none-any.whl

pickle_strategy/__init__.py

@@ -0,0 +1,161 @@
+"""Public contracts and hosting tools for broker-neutral Pickle strategies."""
+
+from .codecs import (
+    StrategyContractError,
+    StrategyDecodeError,
+    broker_account_snapshot_from_dict,
+    broker_account_snapshot_to_dict,
+    dumps_execution_report,
+    dumps_ticket_request,
+    dumps_trade_ticket,
+    execution_report_from_dict,
+    execution_report_to_dict,
+    loads_execution_report,
+    loads_ticket_request,
+    loads_trade_ticket,
+    ticket_request_from_dict,
+    ticket_request_to_dict,
+    trade_ticket_for_request,
+    trade_ticket_from_dict,
+    trade_ticket_to_dict,
+)
+from .loading import StrategyTargetError, load_report_handler, load_strategy
+from .models import (
+    SCHEMA_VERSION,
+    SUPPORTED_SCHEMA_VERSIONS,
+    BrokerAccountSnapshot,
+    CashBalance,
+    ComplianceRule,
+    Direction,
+    ExecutionReport,
+    Fee,
+    OrderExecution,
+    OrderReportStatus,
+    OrderType,
+    Position,
+    PricedPosition,
+    QuantityConformance,
+    ReportStatus,
+    SecurityType,
+    Strategy,
+    TicketRequest,
+    TimeInForce,
+    Trade,
+    TradeTicket,
+    new_ticket_id,
+)
+from .service import (
+    StrategyRejection,
+    create_app,
+    create_report_app,
+    is_report_handler,
+    is_strategy_service,
+    report_handler,
+    strategy_service,
+)
+from .signing import (
+    DEFAULT_REPLAY_WINDOW,
+    DELIVERY_ID_HEADER,
+    EVENT_ID_HEADER,
+    REQUEST_ID_HEADER,
+    SIGNATURE_HEADER,
+    SIGNATURE_VERSION,
+    TIMESTAMP_HEADER,
+    ExpiredSignature,
+    HmacVerifier,
+    InvalidSignature,
+    MalformedSignature,
+    MismatchedEventId,
+    MissingSignature,
+    ReplayCacheExhausted,
+    ReplayedSignature,
+    ReportVerifier,
+    SignatureError,
+    VerifiedReport,
+    VerifiedRequest,
+    format_timestamp,
+    report_signature_headers,
+    report_signing_payload,
+    sign,
+    sign_report,
+    signature_headers,
+    signing_payload,
+)
+
+__all__ = [
+    "broker_account_snapshot_from_dict",
+    "broker_account_snapshot_to_dict",
+    "BrokerAccountSnapshot",
+    "CashBalance",
+    "ComplianceRule",
+    "create_app",
+    "create_report_app",
+    "DEFAULT_REPLAY_WINDOW",
+    "DELIVERY_ID_HEADER",
+    "Direction",
+    "dumps_execution_report",
+    "dumps_ticket_request",
+    "dumps_trade_ticket",
+    "execution_report_from_dict",
+    "execution_report_to_dict",
+    "EVENT_ID_HEADER",
+    "ExecutionReport",
+    "ExpiredSignature",
+    "Fee",
+    "format_timestamp",
+    "HmacVerifier",
+    "InvalidSignature",
+    "is_report_handler",
+    "is_strategy_service",
+    "load_report_handler",
+    "load_strategy",
+    "loads_execution_report",
+    "loads_ticket_request",
+    "loads_trade_ticket",
+    "MalformedSignature",
+    "MismatchedEventId",
+    "MissingSignature",
+    "new_ticket_id",
+    "OrderExecution",
+    "OrderReportStatus",
+    "OrderType",
+    "Position",
+    "PricedPosition",
+    "QuantityConformance",
+    "ReplayCacheExhausted",
+    "ReplayedSignature",
+    "report_handler",
+    "report_signature_headers",
+    "report_signing_payload",
+    "ReportStatus",
+    "ReportVerifier",
+    "REQUEST_ID_HEADER",
+    "SCHEMA_VERSION",
+    "SUPPORTED_SCHEMA_VERSIONS",
+    "SecurityType",
+    "sign",
+    "sign_report",
+    "SIGNATURE_HEADER",
+    "signature_headers",
+    "SIGNATURE_VERSION",
+    "SignatureError",
+    "signing_payload",
+    "Strategy",
+    "strategy_service",
+    "StrategyContractError",
+    "StrategyDecodeError",
+    "StrategyRejection",
+    "StrategyTargetError",
+    "ticket_request_from_dict",
+    "ticket_request_to_dict",
+    "TicketRequest",
+    "TimeInForce",
+    "TIMESTAMP_HEADER",
+    "Trade",
+    "trade_ticket_from_dict",
+    "trade_ticket_for_request",
+    "trade_ticket_to_dict",
+    "TradeTicket",
+    "VerifiedReport",
+    "VerifiedRequest",
+]

pickle_strategy/cli.py

@@ -0,0 +1,206 @@
+"""Command-line entry point for serving partner strategies."""
+
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+from collections.abc import Sequence
+from datetime import timedelta
+from pathlib import Path
+
+import uvicorn
+
+from .loading import StrategyTargetError, load_report_handler, load_strategy
+from .service import ReportFunction, StrategyFunction, create_app
+from .signing import DEFAULT_REPLAY_WINDOW, HmacVerifier, ReportVerifier
+
+# `serve` runs from a strategist's project directory, where the strategy module
+# is usually a plain file rather than an installed distribution.
+ServiceTargetError = StrategyTargetError
+
+LOOPBACK_HOSTS = frozenset({"127.0.0.1", "::1", "localhost"})
+
+
+def load_target(target: str) -> StrategyFunction:
+    """Load a ``module:function`` target, allowing modules in the working directory."""
+    _allow_working_directory()
+    return load_strategy(target)
+
+
+def load_report_target(target: str) -> ReportFunction:
+    """Load a ``module:function`` report handler the same way."""
+    _allow_working_directory()
+    return load_report_handler(target)
+
+
+def _allow_working_directory() -> None:
+    working_directory = str(Path.cwd())
+    if working_directory not in sys.path:
+        sys.path.insert(0, working_directory)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="pickle-strategy")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    serve = commands.add_parser("serve", help="serve a decorated strategy over JSON")
+    serve.add_argument("target", help="decorated strategy as module:function")
+    serve.add_argument("--host", default="127.0.0.1", help="bind address (default: 127.0.0.1)")
+    serve.add_argument("--port", default=8000, type=_port, help="bind port (default: 8000)")
+    # The key is read from the environment rather than accepted as an argument
+    # so it never appears in a process listing or a shell history file.
+    serve.add_argument(
+        "--hmac-secret-env",
+        action="append",
+        default=None,
+        metavar="NAME",
+        help=(
+            "environment variable holding a shared HMAC key; repeat to accept "
+            "several keys during a rotation"
+        ),
+    )
+    serve.add_argument(
+        "--replay-window-seconds",
+        type=_positive_seconds,
+        default=int(DEFAULT_REPLAY_WINDOW.total_seconds()),
+        help="how far a signed timestamp may deviate from now (default: 300)",
+    )
+    serve.add_argument(
+        "--allow-unauthenticated",
+        action="store_true",
+        help="serve unsigned requests; permitted only on a loopback address",
+    )
+    serve.add_argument(
+        "--report-handler",
+        default=None,
+        metavar="MODULE:FUNCTION",
+        help="decorated execution report handler to serve at POST /reports",
+    )
+    serve.add_argument(
+        "--report-secret-env",
+        action="append",
+        default=None,
+        metavar="NAME",
+        help=(
+            "environment variable holding the deployment's callback key, which "
+            "verifies reports; repeat to accept several keys during a rotation"
+        ),
+    )
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    if args.command == "serve":
+        try:
+            strategy = load_target(args.target)
+            handler = (
+                None if args.report_handler is None else load_report_target(args.report_handler)
+            )
+        except StrategyTargetError as exc:
+            parser.error(str(exc))
+        verifier = _build_verifier(parser, args)
+        application = create_app(
+            strategy,
+            verifier=verifier,
+            allow_unauthenticated=verifier is None,
+            report_handler=handler,
+            report_verifier=_build_report_verifier(parser, args),
+            # The flag is loopback-only, and covers both routes from here.
+            allow_unauthenticated_reports=handler is not None and args.allow_unauthenticated,
+        )
+        uvicorn.run(application, host=args.host, port=args.port)
+        return 0
+    parser.error(f"unknown command: {args.command}")
+
+
+def _build_verifier(
+    parser: argparse.ArgumentParser, args: argparse.Namespace
+) -> HmacVerifier | None:
+    secret_variables = args.hmac_secret_env or []
+    if args.allow_unauthenticated:
+        if secret_variables:
+            parser.error("--allow-unauthenticated cannot be combined with --hmac-secret-env")
+        if args.host not in LOOPBACK_HOSTS:
+            parser.error(
+                "--allow-unauthenticated is limited to loopback development; "
+                f"--host {args.host} would accept unsigned requests from the network"
+            )
+        return None
+    if not secret_variables:
+        parser.error(
+            "pass --hmac-secret-env NAME to verify Pickle's signature, or "
+            "--allow-unauthenticated for loopback development"
+        )
+    return HmacVerifier(
+        _secrets(parser, secret_variables),
+        replay_window=timedelta(seconds=args.replay_window_seconds),
+    )
+
+
+def _build_report_verifier(
+    parser: argparse.ArgumentParser, args: argparse.Namespace
+) -> ReportVerifier | None:
+    secret_variables = args.report_secret_env or []
+    if args.report_handler is None:
+        if secret_variables:
+            parser.error("--report-secret-env needs --report-handler")
+        return None
+    if args.allow_unauthenticated:
+        if secret_variables:
+            parser.error("--allow-unauthenticated cannot be combined with --report-secret-env")
+        return None
+    if not secret_variables:
+        parser.error(
+            "pass --report-secret-env NAME with the deployment's callback key to "
+            "verify the reports Pickle sends"
+        )
+    callback_keys = _secrets(parser, secret_variables)
+    # Reports are signed with the callback key, which ADR 0016 keeps apart
+    # from the key that signs strategy requests. Compared by value, so two
+    # variables holding one key are caught too; neither value is printed.
+    if set(callback_keys) & set(_secrets(parser, args.hmac_secret_env or [])):
+        parser.error(
+            "--report-secret-env and --hmac-secret-env hold the same key; reports "
+            "are signed with the deployment's callback key, not its request key"
+        )
+    return ReportVerifier(
+        callback_keys,
+        replay_window=timedelta(seconds=args.replay_window_seconds),
+    )
+
+
+def _secrets(parser: argparse.ArgumentParser, variables: Sequence[str]) -> list[str]:
+    secrets = []
+    for name in variables:
+        value = os.environ.get(name)
+        if not value:
+            parser.error(f"environment variable {name} is unset or empty")
+        secrets.append(value)
+    return secrets
+
+
+def _port(value: str) -> int:
+    try:
+        port = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("port must be an integer") from exc
+    if not 1 <= port <= 65535:
+        raise argparse.ArgumentTypeError("port must be between 1 and 65535")
+    return port
+
+
+def _positive_seconds(value: str) -> int:
+    try:
+        seconds = int(value)
+    except ValueError as exc:
+        raise argparse.ArgumentTypeError("seconds must be an integer") from exc
+    if seconds <= 0:
+        raise argparse.ArgumentTypeError("seconds must be positive")
+    return seconds
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())