sealform 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
sealform/__init__.py ADDED
@@ -0,0 +1,9 @@
1
+ """Manage SignPath.io organizations as code."""
2
+
3
+ from importlib.metadata import PackageNotFoundError, version
4
+
5
+ try:
6
+ # set at build time from the latest vX.Y.Z git tag (uv-dynamic-versioning)
7
+ __version__ = version("sealform")
8
+ except PackageNotFoundError: # running from a source tree that is not installed
9
+ __version__ = "0.0.0"
sealform/__main__.py ADDED
@@ -0,0 +1,4 @@
1
+ from sealform.cli import main
2
+
3
+ if __name__ == "__main__":
4
+ main()
File without changes
sealform/api/client.py ADDED
@@ -0,0 +1,272 @@
1
+ """Typed client for the SignPath API operations used by sealform."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+ from urllib.parse import quote
7
+
8
+ from pydantic import TypeAdapter
9
+
10
+ from sealform.api.http import HttpSession, Response
11
+ from sealform.api.models import (
12
+ Certificate,
13
+ CIUserDetail,
14
+ CreatedCIUser,
15
+ InteractiveUserDetail,
16
+ Me,
17
+ Organization,
18
+ Participant,
19
+ PipelinePolicyDetail,
20
+ PipelinePolicyListItem,
21
+ ProjectDetail,
22
+ ProjectListItem,
23
+ RegeneratedToken,
24
+ SigningPolicyDetail,
25
+ TrustedBuildSystem,
26
+ UserGroupDetail,
27
+ )
28
+
29
+ _participants = TypeAdapter(list[Participant])
30
+ _projects = TypeAdapter(list[ProjectListItem])
31
+ _certificates = TypeAdapter(list[Certificate])
32
+ _tbs = TypeAdapter(list[TrustedBuildSystem])
33
+ _pipeline_policies = TypeAdapter(list[PipelinePolicyListItem])
34
+
35
+
36
+ def _seg(value: str) -> str:
37
+ return quote(value, safe="")
38
+
39
+
40
+ class SignPathClient:
41
+ def __init__(self, http: HttpSession) -> None:
42
+ self.http = http
43
+
44
+ @property
45
+ def organization_id(self) -> str:
46
+ return self.http.organization_id
47
+
48
+ def close(self) -> None:
49
+ self.http.close()
50
+
51
+ # ------------------------------------------------------------------ organization
52
+
53
+ def me(self) -> Me:
54
+ return Me.model_validate(self.http.get("/Users/Me").json())
55
+
56
+ def organization(self) -> Organization:
57
+ return Organization.model_validate(self.http.get("/Organization").json())
58
+
59
+ def certificates(self) -> list[Certificate]:
60
+ return _certificates.validate_python(self.http.get("/Certificates").json())
61
+
62
+ def trusted_build_systems(self) -> list[TrustedBuildSystem]:
63
+ return _tbs.validate_python(self.http.get("/TrustedBuildSystems").json())
64
+
65
+ # ------------------------------------------------------------------ users and groups
66
+
67
+ def ci_users(self) -> list[Participant]:
68
+ return _participants.validate_python(self.http.get("/CIUsers").json())
69
+
70
+ def ci_user(self, user_id: str) -> CIUserDetail:
71
+ return CIUserDetail.model_validate(self.http.get(f"/CIUsers/{_seg(user_id)}").json())
72
+
73
+ def ci_user_raw(self, user_id: str) -> Any:
74
+ return self.http.get(f"/CIUsers/{_seg(user_id)}").json()
75
+
76
+ def create_ci_user(
77
+ self, name: str, description: str | None, notification_email: str | None
78
+ ) -> CreatedCIUser:
79
+ body = {"name": name, "description": description, "notificationEmailAddress": notification_email}
80
+ return CreatedCIUser.model_validate(self.http.post("/CIUsers", body).json())
81
+
82
+ def edit_ci_user(self, user_id: str, name: str, description: str | None) -> None:
83
+ self.http.post(f"/CIUsers/{_seg(user_id)}/Edit", {"name": name, "description": description})
84
+
85
+ def change_ci_user_notification_email(self, user_id: str, email: str | None) -> None:
86
+ self.http.post(
87
+ f"/CIUsers/{_seg(user_id)}/ChangeNotificationEmailAddress", {"notificationEmailAddress": email}
88
+ )
89
+
90
+ def activate_ci_user(self, user_id: str) -> None:
91
+ self.http.post(f"/CIUsers/{_seg(user_id)}/Activate")
92
+
93
+ def deactivate_ci_user(self, user_id: str) -> None:
94
+ self.http.post(f"/CIUsers/{_seg(user_id)}/Deactivate")
95
+
96
+ def regenerate_ci_user_token(self, user_id: str) -> RegeneratedToken:
97
+ return RegeneratedToken.model_validate(
98
+ self.http.post(f"/CIUsers/{_seg(user_id)}/RegenerateApiToken").json()
99
+ )
100
+
101
+ def interactive_users(self) -> list[Participant]:
102
+ return _participants.validate_python(self.http.get("/InteractiveUsers").json())
103
+
104
+ def interactive_user(self, user_id: str) -> InteractiveUserDetail:
105
+ return InteractiveUserDetail.model_validate(
106
+ self.http.get(f"/InteractiveUsers/{_seg(user_id)}").json()
107
+ )
108
+
109
+ def user_groups(self) -> list[Participant]:
110
+ return _participants.validate_python(self.http.get("/UserGroups").json())
111
+
112
+ def user_group(self, group_id: str) -> UserGroupDetail:
113
+ return UserGroupDetail.model_validate(self.http.get(f"/UserGroups/{_seg(group_id)}").json())
114
+
115
+ # ------------------------------------------------------------------ projects
116
+
117
+ def projects(self) -> list[ProjectListItem]:
118
+ return _projects.validate_python(self.http.get("/Projects").json())
119
+
120
+ def project_raw(self, slug: str) -> Any:
121
+ return self.http.get(f"/Projects/{_seg(slug)}").json()
122
+
123
+ def project(self, slug: str) -> ProjectDetail:
124
+ return ProjectDetail.model_validate(self.project_raw(slug))
125
+
126
+ def create_project(
127
+ self,
128
+ *,
129
+ name: str,
130
+ slug: str,
131
+ description: str | None,
132
+ repository_urls: list[str],
133
+ reader_ids: list[str],
134
+ configurator_ids: list[str],
135
+ artifact_configuration_xml: str,
136
+ ) -> None:
137
+ self.http.post(
138
+ "/Projects",
139
+ {
140
+ "name": name,
141
+ "slug": slug,
142
+ "description": description,
143
+ "repositoryUrls": repository_urls,
144
+ "readerIds": reader_ids,
145
+ "configuratorIds": configurator_ids,
146
+ "artifactConfigurationXml": artifact_configuration_xml,
147
+ },
148
+ )
149
+
150
+ def edit_project(
151
+ self,
152
+ current_slug: str,
153
+ *,
154
+ name: str,
155
+ slug: str,
156
+ description: str | None,
157
+ repository_urls: list[str],
158
+ reader_ids: list[str],
159
+ configurator_ids: list[str],
160
+ ) -> None:
161
+ self.http.post(
162
+ f"/Projects/{_seg(current_slug)}/Edit",
163
+ {
164
+ "name": name,
165
+ "slug": slug,
166
+ "description": description,
167
+ "repositoryUrls": repository_urls,
168
+ "readerIds": reader_ids,
169
+ "configuratorIds": configurator_ids,
170
+ },
171
+ )
172
+
173
+ def activate_project(self, slug: str) -> None:
174
+ self.http.post(f"/Projects/{_seg(slug)}/Activate")
175
+
176
+ def deactivate_project(self, slug: str) -> None:
177
+ self.http.post(f"/Projects/{_seg(slug)}/Deactivate")
178
+
179
+ def set_default_artifact_configuration(self, project: str, ac_slug: str) -> None:
180
+ self.http.post(
181
+ f"/Projects/{_seg(project)}/SetDefaultArtifactConfiguration",
182
+ {"artifactConfigurationSlug": ac_slug},
183
+ )
184
+
185
+ def link_trusted_build_system(self, project: str, tbs_slug: str) -> None:
186
+ self.http.post(
187
+ f"/Projects/{_seg(project)}/TrustedBuildSystemLinks", {"trustedBuildSystemSlug": tbs_slug}
188
+ )
189
+
190
+ # ------------------------------------------------------------------ artifact configurations
191
+
192
+ def artifact_configuration_xml(self, project: str, ac_slug: str) -> str:
193
+ path = f"/Projects/{_seg(project)}/ArtifactConfigurations/{_seg(ac_slug)}/Xml"
194
+ return self.http.get(path, accept="application/xml").text
195
+
196
+ def add_artifact_configuration(
197
+ self, project: str, *, name: str, slug: str, description: str | None, xml: str
198
+ ) -> None:
199
+ self.http.post(
200
+ f"/Projects/{_seg(project)}/ArtifactConfigurations",
201
+ {"name": name, "slug": slug, "description": description, "artifactConfigurationXml": xml},
202
+ )
203
+
204
+ def edit_artifact_configuration(
205
+ self, project: str, current_slug: str, *, name: str, slug: str, description: str | None
206
+ ) -> None:
207
+ self.http.post(
208
+ f"/Projects/{_seg(project)}/ArtifactConfigurations/{_seg(current_slug)}/Edit",
209
+ {"name": name, "slug": slug, "description": description},
210
+ )
211
+
212
+ def edit_artifact_configuration_xml(self, project: str, ac_slug: str, xml: str) -> None:
213
+ self.http.post(
214
+ f"/Projects/{_seg(project)}/ArtifactConfigurations/{_seg(ac_slug)}/EditXml",
215
+ {"artifactConfigurationXml": xml},
216
+ )
217
+
218
+ def activate_artifact_configuration(self, project: str, ac_slug: str) -> None:
219
+ self.http.post(f"/Projects/{_seg(project)}/ArtifactConfigurations/{_seg(ac_slug)}/Activate")
220
+
221
+ def deactivate_artifact_configuration(self, project: str, ac_slug: str) -> None:
222
+ self.http.post(f"/Projects/{_seg(project)}/ArtifactConfigurations/{_seg(ac_slug)}/Deactivate")
223
+
224
+ # ------------------------------------------------------------------ signing policies
225
+
226
+ def signing_policy_raw(self, project: str, sp_slug: str) -> Any:
227
+ return self.http.get(
228
+ f"/Projects/{_seg(project)}/SigningPolicies/{_seg(sp_slug)}",
229
+ params={"includePipelinePolicyContent": "false"},
230
+ ).json()
231
+
232
+ def signing_policy(self, project: str, sp_slug: str) -> SigningPolicyDetail:
233
+ return SigningPolicyDetail.model_validate(self.signing_policy_raw(project, sp_slug))
234
+
235
+ def add_signing_policy(self, project: str, body: dict[str, Any]) -> None:
236
+ self.http.post(f"/Projects/{_seg(project)}/SigningPolicies", body)
237
+
238
+ def edit_signing_policy(self, project: str, current_slug: str, body: dict[str, Any]) -> None:
239
+ self.http.post(f"/Projects/{_seg(project)}/SigningPolicies/{_seg(current_slug)}/Edit", body)
240
+
241
+ def activate_signing_policy(self, project: str, sp_slug: str) -> None:
242
+ self.http.post(f"/Projects/{_seg(project)}/SigningPolicies/{_seg(sp_slug)}/Activate")
243
+
244
+ def deactivate_signing_policy(self, project: str, sp_slug: str) -> None:
245
+ self.http.post(f"/Projects/{_seg(project)}/SigningPolicies/{_seg(sp_slug)}/Deactivate")
246
+
247
+ # ------------------------------------------------------------------ pipeline policies
248
+
249
+ def pipeline_policies(self) -> list[PipelinePolicyListItem]:
250
+ return _pipeline_policies.validate_python(self.http.get("/PipelinePolicies").json())
251
+
252
+ def pipeline_policy_raw(self, slug: str) -> Any:
253
+ return self.http.get(f"/PipelinePolicies/{_seg(slug)}").json()
254
+
255
+ def pipeline_policy(self, slug: str) -> PipelinePolicyDetail:
256
+ return PipelinePolicyDetail.model_validate(self.pipeline_policy_raw(slug))
257
+
258
+ def create_pipeline_policy(self, body: dict[str, Any]) -> None:
259
+ self.http.post("/PipelinePolicies", body)
260
+
261
+ def edit_pipeline_policy(self, current_slug: str, body: dict[str, Any]) -> None:
262
+ self.http.post(f"/PipelinePolicies/{_seg(current_slug)}/Edit", body)
263
+
264
+ def activate_pipeline_policy(self, slug: str) -> None:
265
+ self.http.post(f"/PipelinePolicies/{_seg(slug)}/Activate")
266
+
267
+ def deactivate_pipeline_policy(self, slug: str) -> None:
268
+ self.http.post(f"/PipelinePolicies/{_seg(slug)}/Deactivate")
269
+
270
+
271
+ def response_json(response: Response) -> Any:
272
+ return response.json()
sealform/api/errors.py ADDED
@@ -0,0 +1,62 @@
1
+ """API error types."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from typing import Any
6
+
7
+
8
+ class ApiError(Exception):
9
+ """An HTTP error answered by the SignPath API (RFC 9457 problem details when available)."""
10
+
11
+ def __init__(
12
+ self,
13
+ method: str,
14
+ path: str,
15
+ status: int,
16
+ title: str | None = None,
17
+ detail: str | None = None,
18
+ errors: dict[str, Any] | None = None,
19
+ trace_id: str | None = None,
20
+ ) -> None:
21
+ self.method = method
22
+ self.path = path
23
+ self.status = status
24
+ self.title = title
25
+ self.detail = detail
26
+ self.errors = errors or {}
27
+ self.trace_id = trace_id
28
+ super().__init__(str(self))
29
+
30
+ @property
31
+ def reason(self) -> str:
32
+ parts: list[str] = []
33
+ if self.detail:
34
+ parts.append(self.detail)
35
+ for field, messages in self.errors.items():
36
+ if isinstance(messages, list):
37
+ parts.extend(f"{field}: {m}" for m in messages)
38
+ else:
39
+ parts.append(f"{field}: {messages}")
40
+ if not parts and self.title:
41
+ parts.append(self.title)
42
+ return "; ".join(parts) or "no details"
43
+
44
+ def __str__(self) -> str:
45
+ trace = f" (trace {self.trace_id})" if self.trace_id else ""
46
+ return f"{self.method} {self.path} -> HTTP {self.status}: {self.reason}{trace}"
47
+
48
+ @property
49
+ def feature_disabled(self) -> bool:
50
+ return self.status == 403 and "feature is disabled" in (self.detail or "")
51
+
52
+
53
+ class NotFoundError(ApiError):
54
+ pass
55
+
56
+
57
+ class TransportError(Exception):
58
+ """The API could not be reached."""
59
+
60
+
61
+ class StalePlanError(Exception):
62
+ """A resource changed between plan and apply (emulated precondition failed)."""
sealform/api/http.py ADDED
@@ -0,0 +1,245 @@
1
+ """HTTP session: authentication, conditional requests, retries (see ADR-0011)."""
2
+
3
+ from __future__ import annotations
4
+
5
+ import logging
6
+ import random
7
+ import threading
8
+ import time
9
+ from collections.abc import Callable
10
+ from dataclasses import dataclass
11
+ from email.utils import parsedate_to_datetime
12
+ from typing import Any
13
+
14
+ import httpx
15
+ from pydantic import SecretStr
16
+
17
+ from sealform import __version__
18
+ from sealform.api.errors import ApiError, NotFoundError, TransportError
19
+
20
+ log = logging.getLogger("sealform.api")
21
+
22
+ USER_AGENT = f"sealform/{__version__} (+https://github.com/eclipse-csi/sealform)"
23
+ RETRYABLE_GET = {429, 502, 503, 504}
24
+ RETRYABLE_WRITE = {429} # the request was not processed
25
+
26
+
27
+ @dataclass
28
+ class _Cached:
29
+ etag: str | None
30
+ last_modified: str | None
31
+ status_code: int
32
+ content: bytes
33
+ content_type: str | None
34
+
35
+
36
+ @dataclass
37
+ class Response:
38
+ status_code: int
39
+ content: bytes
40
+ headers: dict[str, str]
41
+ from_cache: bool = False
42
+
43
+ def json(self) -> Any:
44
+ import json
45
+
46
+ return json.loads(self.content) if self.content else None
47
+
48
+ @property
49
+ def text(self) -> str:
50
+ return self.content.decode("utf-8")
51
+
52
+ @property
53
+ def etag(self) -> str | None:
54
+ return self.headers.get("etag")
55
+
56
+
57
+ class HttpSession:
58
+ """Authenticated session bound to one organization.
59
+
60
+ * GET requests are conditional: validators (ETag / Last-Modified) seen on previous
61
+ responses are sent back as If-None-Match / If-Modified-Since and a 304 is served
62
+ from the cache. SignPath does not emit validators today, so this is inert until it does.
63
+ * Writes send If-Match when an ETag is known for the target resource.
64
+ * 429/502/503/504 on GET and 429 on writes are retried with exponential backoff and
65
+ Retry-After.
66
+ """
67
+
68
+ def __init__(
69
+ self,
70
+ api_url: str,
71
+ organization_id: str,
72
+ token: SecretStr,
73
+ *,
74
+ transport: httpx.BaseTransport | None = None,
75
+ timeout: float = 60.0,
76
+ max_retries: int = 4,
77
+ sleep: Callable[[float], None] = time.sleep,
78
+ max_connections: int = 16,
79
+ ) -> None:
80
+ self.api_url = api_url.rstrip("/")
81
+ self.organization_id = organization_id
82
+ self.base_url = f"{self.api_url}/v1/{organization_id}"
83
+ self._max_retries = max_retries
84
+ self._sleep = sleep
85
+ self._cache: dict[str, _Cached] = {}
86
+ self._lock = threading.Lock()
87
+ self.request_count = 0
88
+ self._client = httpx.Client(
89
+ transport=transport,
90
+ timeout=timeout,
91
+ headers={
92
+ "Authorization": f"Bearer {token.get_secret_value()}",
93
+ "User-Agent": USER_AGENT,
94
+ "Accept": "application/json",
95
+ },
96
+ limits=httpx.Limits(max_connections=max_connections, max_keepalive_connections=max_connections),
97
+ follow_redirects=False,
98
+ )
99
+
100
+ def close(self) -> None:
101
+ self._client.close()
102
+
103
+ def __enter__(self) -> HttpSession:
104
+ return self
105
+
106
+ def __exit__(self, *exc: object) -> None:
107
+ self.close()
108
+
109
+ # ------------------------------------------------------------------ helpers
110
+
111
+ def url(self, path: str) -> str:
112
+ if path.startswith("http://") or path.startswith("https://"):
113
+ return path
114
+ return f"{self.base_url}{path}"
115
+
116
+ def known_etag(self, path: str) -> str | None:
117
+ with self._lock:
118
+ cached = self._cache.get(self.url(path))
119
+ return cached.etag if cached else None
120
+
121
+ def _backoff(self, attempt: int, response: httpx.Response | None) -> float:
122
+ if response is not None:
123
+ retry_after = response.headers.get("retry-after")
124
+ if retry_after:
125
+ try:
126
+ return min(float(retry_after), 120.0)
127
+ except ValueError:
128
+ try:
129
+ delta = parsedate_to_datetime(retry_after).timestamp() - time.time()
130
+ return max(0.0, min(delta, 120.0))
131
+ except (TypeError, ValueError):
132
+ pass
133
+ return float(min(30.0, 0.5 * 2**attempt + random.uniform(0, 0.25))) # noqa: S311
134
+
135
+ def _raise_for(self, method: str, path: str, response: httpx.Response) -> None:
136
+ title = detail = trace = None
137
+ errors: dict[str, Any] | None = None
138
+ try:
139
+ body = response.json()
140
+ if isinstance(body, dict):
141
+ title = body.get("title")
142
+ detail = body.get("detail")
143
+ errors = body.get("errors") if isinstance(body.get("errors"), dict) else None
144
+ trace = body.get("traceId")
145
+ except ValueError:
146
+ detail = response.text[:500] or None
147
+ cls = NotFoundError if response.status_code == 404 else ApiError
148
+ raise cls(method, path, response.status_code, title, detail, errors, trace)
149
+
150
+ # ------------------------------------------------------------------ requests
151
+
152
+ def request(
153
+ self,
154
+ method: str,
155
+ path: str,
156
+ *,
157
+ json: Any = None,
158
+ params: dict[str, Any] | None = None,
159
+ accept: str | None = None,
160
+ if_match: str | None = None,
161
+ ) -> Response:
162
+ url = self.url(path)
163
+ is_get = method == "GET"
164
+ headers: dict[str, str] = {}
165
+ if accept:
166
+ headers["Accept"] = accept
167
+ cache_key = str(httpx.URL(url, params=params)) if is_get else url
168
+ cached: _Cached | None = None
169
+ if is_get:
170
+ with self._lock:
171
+ cached = self._cache.get(cache_key)
172
+ if cached is not None:
173
+ if cached.etag:
174
+ headers["If-None-Match"] = cached.etag
175
+ if cached.last_modified:
176
+ headers["If-Modified-Since"] = cached.last_modified
177
+ else:
178
+ etag = if_match
179
+ if etag is None:
180
+ with self._lock:
181
+ target = self._cache.get(url.rsplit("/", 1)[0])
182
+ etag = target.etag if target else None
183
+ if etag:
184
+ headers["If-Match"] = etag
185
+
186
+ retryable = RETRYABLE_GET if is_get else RETRYABLE_WRITE
187
+ attempt = 0
188
+ while True:
189
+ started = time.monotonic()
190
+ try:
191
+ response = self._client.request(method, url, json=json, params=params, headers=headers)
192
+ except httpx.TransportError as e:
193
+ if is_get and attempt < self._max_retries:
194
+ delay = self._backoff(attempt, None)
195
+ log.debug("%s %s failed (%s), retrying in %.1fs", method, path, e, delay)
196
+ self._sleep(delay)
197
+ attempt += 1
198
+ continue
199
+ raise TransportError(f"{method} {path}: {e}") from e
200
+ with self._lock:
201
+ self.request_count += 1
202
+ log.debug(
203
+ "%s %s -> %s (%.0f ms)",
204
+ method,
205
+ path,
206
+ response.status_code,
207
+ (time.monotonic() - started) * 1000,
208
+ )
209
+ if response.status_code in retryable and attempt < self._max_retries:
210
+ delay = self._backoff(attempt, response)
211
+ log.info("%s %s -> %s, retrying in %.1fs", method, path, response.status_code, delay)
212
+ self._sleep(delay)
213
+ attempt += 1
214
+ continue
215
+ break
216
+
217
+ if is_get and response.status_code == 304 and cached is not None:
218
+ return Response(cached.status_code, cached.content, {"etag": cached.etag or ""}, from_cache=True)
219
+ if response.status_code >= 400:
220
+ self._raise_for(method, path, response)
221
+ lowered = {k.lower(): v for k, v in response.headers.items()}
222
+ if is_get:
223
+ etag = lowered.get("etag")
224
+ last_modified = lowered.get("last-modified")
225
+ if etag or last_modified:
226
+ with self._lock:
227
+ self._cache[cache_key] = _Cached(
228
+ etag,
229
+ last_modified,
230
+ response.status_code,
231
+ response.content,
232
+ lowered.get("content-type"),
233
+ )
234
+ else:
235
+ # our own write invalidates what we know about the resource
236
+ with self._lock:
237
+ for key in [k for k in self._cache if k.startswith(url.rsplit("/", 1)[0])]:
238
+ del self._cache[key]
239
+ return Response(response.status_code, response.content, lowered)
240
+
241
+ def get(self, path: str, **kwargs: Any) -> Response:
242
+ return self.request("GET", path, **kwargs)
243
+
244
+ def post(self, path: str, json: Any = None, **kwargs: Any) -> Response:
245
+ return self.request("POST", path, json=json, **kwargs)