2020
2121@dataclass (frozen = True )
2222class WorkerBoundary :
23+ """The credential, permission set, and concurrency namespace one review worker runs under."""
24+
2325 credential : str
2426 permissions : tuple [str , ...]
2527 concurrency_namespace : str
2628 cancel_in_progress : bool = True
2729
2830 def concurrency_group (self , request : AdmissionRequest ) -> str :
31+ """Return this worker's `{namespace}-{repository}-{pull_request}` concurrency group."""
2932 return (
3033 f"{ self .concurrency_namespace } -{ request .repository } -{ request .pull_request } "
3134 )
@@ -52,6 +55,8 @@ def concurrency_group(self, request: AdmissionRequest) -> str:
5255
5356@dataclass (frozen = True )
5457class AdmissionRequest :
58+ """One validated request to admit a review worker onto a specific PR head."""
59+
5560 repository : str
5661 pull_request : int
5762 head_sha : str
@@ -68,6 +73,7 @@ def create(
6873 component : str ,
6974 sequence : int ,
7075 ) -> AdmissionRequest :
76+ """Validate and normalize raw fields into an `AdmissionRequest`."""
7177 if isinstance (pull_request , bool ) or not isinstance (pull_request , int ):
7278 raise TypeError ("pull request must be an integer" )
7379 if isinstance (sequence , bool ) or not isinstance (sequence , int ):
@@ -87,35 +93,45 @@ def create(
8793
8894 @property
8995 def identity (self ) -> str :
96+ """Return the unique key identifying this exact request (including its sequence)."""
9097 return f"{ self .repository } #{ self .pull_request } @{ self .head_sha } :{ self .component } "
9198
9299 @property
93100 def stream (self ) -> str :
101+ """Return the key identifying this request's PR+component stream across sequences."""
94102 return f"{ self .repository } #{ self .pull_request } :{ self .component } "
95103
96104
97105@dataclass (frozen = True )
98106class RequestRecord :
107+ """An admission request paired with its current lifecycle status."""
108+
99109 request : AdmissionRequest
100110 status : str
101111
102112
103113@dataclass (frozen = True )
104114class DispatchLease :
115+ """A request that has been granted a worker boundary to run under."""
116+
105117 request : AdmissionRequest
106118 boundary : WorkerBoundary
107119
108120
109121@dataclass (frozen = True )
110122class ControllerState :
123+ """The durable admission controller's full state: known records and per-stream sequences."""
124+
111125 records : dict [str , RequestRecord ]
112126 latest_sequences : dict [str , int ]
113127
114128 @classmethod
115129 def empty (cls ) -> ControllerState :
130+ """Return the initial state with no records and no sequences observed yet."""
116131 return cls ({}, {})
117132
118133 def to_json (self ) -> str :
134+ """Serialize this state to its canonical, deterministically-ordered JSON form."""
119135 payload = {
120136 "latest_sequences" : self .latest_sequences ,
121137 "records" : {
@@ -130,6 +146,7 @@ def to_json(self) -> str:
130146
131147 @classmethod
132148 def from_json (cls , value : str ) -> ControllerState :
149+ """Parse and fully validate a state snapshot, rejecting any inconsistent JSON."""
133150 payload = json .loads (value )
134151 if not isinstance (payload , dict ):
135152 raise TypeError ("durable admission state must be an object" )
@@ -204,6 +221,7 @@ def _open_regular_nofollow(path: Path, flags: int, mode: int = 0o600) -> int:
204221
205222
206223def _read_state (path : Path ) -> ControllerState :
224+ """Read and parse one state file, rejecting a symlink and non-UTF-8 content."""
207225 descriptor = _open_regular_nofollow (path , os .O_RDONLY )
208226 try :
209227 with os .fdopen (descriptor , encoding = "utf-8" ) as stream :
@@ -282,6 +300,8 @@ def update_state_file(
282300
283301@dataclass (frozen = True )
284302class DispatchPlan :
303+ """The result of one admission pass: the updated state, grants, and rejections."""
304+
285305 state : ControllerState
286306 dispatches : tuple [DispatchLease , ...]
287307 rejections : dict [str , str ]
0 commit comments