|
| 1 | +"""Backend abstraction for rule-draft submission. |
| 2 | +
|
| 3 | +The Osprey engine doesn't care where rules live. Different deployments use |
| 4 | +different hosting: GitHub or Enterprise, GitLab, Tangled, an internal Gerrit, |
| 5 | +or a filesystem on a shared volume. Each is one implementation of the |
| 6 | +RuleSubmissionBackend Protocol below. |
| 7 | +
|
| 8 | +`load_backend()` reads `OSPREY_RULES_SUBMISSION_BACKEND` and instantiates the |
| 9 | +chosen backend with its own env vars. Defaults to `null` so an unconfigured |
| 10 | +install ships safe; adopters opt into a backend explicitly. |
| 11 | +
|
| 12 | +Adopter docs (env vars per backend, how to choose one): see |
| 13 | +`docs/user/manage.md`. |
| 14 | +
|
| 15 | +Adding a new backend: implement a class with `submit_draft` and |
| 16 | +`list_pending_drafts` matching the Protocol below, add a case in |
| 17 | +`load_backend()`, and update the "unknown backend" error message here plus |
| 18 | +the "no backend configured" message in `_rule_drafts_null.py`. The existing |
| 19 | +`_rule_drafts_github.py` module is a working template for HTTP-backed |
| 20 | +adapters; `_rule_drafts_local.py` for filesystem. |
| 21 | +""" |
| 22 | + |
| 23 | +from __future__ import annotations |
| 24 | + |
| 25 | +import os |
| 26 | +from dataclasses import dataclass, field |
| 27 | +from typing import Any, Protocol |
| 28 | + |
| 29 | + |
| 30 | +class RuleDraftBackendError(Exception): |
| 31 | + """Raised by any backend method when the operation cannot complete.""" |
| 32 | + |
| 33 | + def __init__(self, message: str, status_code: int = 502): |
| 34 | + super().__init__(message) |
| 35 | + self.message = message |
| 36 | + self.status_code = status_code |
| 37 | + |
| 38 | + |
| 39 | +@dataclass(frozen=True) |
| 40 | +class SubmissionResult: |
| 41 | + """Backend-neutral submit_draft return value. |
| 42 | +
|
| 43 | + `title` and `url` are what the UI surfaces in the success banner; `extras` |
| 44 | + carries backend-specific fields (PR number, branch, etc.) for adopters |
| 45 | + whose UI variants want to render more detail. |
| 46 | + """ |
| 47 | + |
| 48 | + title: str |
| 49 | + url: str | None |
| 50 | + main_sml_updated: bool = False |
| 51 | + extras: dict[str, Any] = field(default_factory=dict) |
| 52 | + |
| 53 | + def to_json(self) -> dict[str, Any]: |
| 54 | + # Spread extras first so the canonical fields always win: a backend that |
| 55 | + # happens to name an extra `title`/`url`/`main_sml_updated` can't shadow |
| 56 | + # the contract fields the UI depends on. |
| 57 | + return { |
| 58 | + **self.extras, |
| 59 | + 'title': self.title, |
| 60 | + 'url': self.url, |
| 61 | + 'main_sml_updated': self.main_sml_updated, |
| 62 | + } |
| 63 | + |
| 64 | + |
| 65 | +@dataclass(frozen=True) |
| 66 | +class PendingDraft: |
| 67 | + """Backend-neutral entry for the pending-drafts list.""" |
| 68 | + |
| 69 | + title: str |
| 70 | + url: str |
| 71 | + author: str |
| 72 | + created_at: str |
| 73 | + touched_files: list[str] |
| 74 | + extras: dict[str, Any] = field(default_factory=dict) |
| 75 | + |
| 76 | + def to_json(self) -> dict[str, Any]: |
| 77 | + # Spread extras first so backend-specific keys can't shadow the |
| 78 | + # canonical fields the UI depends on. |
| 79 | + return { |
| 80 | + **self.extras, |
| 81 | + 'title': self.title, |
| 82 | + 'url': self.url, |
| 83 | + 'author': self.author, |
| 84 | + 'created_at': self.created_at, |
| 85 | + 'touched_files': self.touched_files, |
| 86 | + } |
| 87 | + |
| 88 | + |
| 89 | +class RuleSubmissionBackend(Protocol): |
| 90 | + """The contract every submission backend implements. |
| 91 | +
|
| 92 | + Implementations: |
| 93 | + - submit a draft (create whatever the backend's review unit is) |
| 94 | + - optionally wire the new rule into main.sml as part of the same submission |
| 95 | + - list whatever's currently in review |
| 96 | +
|
| 97 | + Implementations raise `RuleDraftBackendError` for any failure path. |
| 98 | + """ |
| 99 | + |
| 100 | + name: str |
| 101 | + |
| 102 | + def submit_draft( |
| 103 | + self, |
| 104 | + *, |
| 105 | + draft_path: str, |
| 106 | + sml_source: str, |
| 107 | + rule_name: str, |
| 108 | + summary: str, |
| 109 | + author_email: str, |
| 110 | + is_new_rule: bool, |
| 111 | + wire_into_main: bool, |
| 112 | + ) -> SubmissionResult: ... |
| 113 | + |
| 114 | + def list_pending_drafts(self) -> list[PendingDraft]: ... |
| 115 | + |
| 116 | + |
| 117 | +def load_backend() -> RuleSubmissionBackend: |
| 118 | + """Select and instantiate the configured backend. |
| 119 | +
|
| 120 | + `OSPREY_RULES_SUBMISSION_BACKEND` picks one of: github, local, null. |
| 121 | + Unset or empty defaults to `null`. Unknown values raise so a typo doesn't |
| 122 | + silently degrade to no-op submission. |
| 123 | + """ |
| 124 | + name = (os.environ.get('OSPREY_RULES_SUBMISSION_BACKEND') or 'null').strip().lower() |
| 125 | + |
| 126 | + # Imports are deferred to keep the Protocol module dependency-free. |
| 127 | + if name == 'null': |
| 128 | + from ._rule_drafts_null import NullBackend |
| 129 | + |
| 130 | + return NullBackend() |
| 131 | + if name == 'github': |
| 132 | + from ._rule_drafts_github import GitHubBackend |
| 133 | + |
| 134 | + return GitHubBackend.from_env() |
| 135 | + if name == 'local': |
| 136 | + from ._rule_drafts_local import LocalBackend |
| 137 | + |
| 138 | + return LocalBackend.from_env() |
| 139 | + raise RuleDraftBackendError( |
| 140 | + f'Unknown OSPREY_RULES_SUBMISSION_BACKEND {name!r}; valid values are github, local, null.', |
| 141 | + status_code=500, |
| 142 | + ) |
0 commit comments