creat01deployengine 1.0.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.
- creat01deployengine/AI_USAGE.md +68 -0
- creat01deployengine/__init__.py +22 -0
- creat01deployengine/client.py +276 -0
- creat01deployengine/errors.py +51 -0
- creat01deployengine/logging/__init__.py +5 -0
- creat01deployengine/logging/reporter.py +66 -0
- creat01deployengine/models/__init__.py +14 -0
- creat01deployengine/models/common.py +16 -0
- creat01deployengine/models/infrastructure.py +27 -0
- creat01deployengine/models/projects.py +17 -0
- creat01deployengine/py.typed +1 -0
- creat01deployengine/resources/__init__.py +34 -0
- creat01deployengine/resources/alerts.py +13 -0
- creat01deployengine/resources/authentication.py +38 -0
- creat01deployengine/resources/base.py +44 -0
- creat01deployengine/resources/certificates.py +19 -0
- creat01deployengine/resources/domains.py +27 -0
- creat01deployengine/resources/feedback.py +15 -0
- creat01deployengine/resources/load_balancers.py +33 -0
- creat01deployengine/resources/machines.py +21 -0
- creat01deployengine/resources/payments.py +25 -0
- creat01deployengine/resources/projects.py +37 -0
- creat01deployengine/resources/security_groups.py +28 -0
- creat01deployengine/resources/tracking.py +37 -0
- creat01deployengine/resources/workflows.py +19 -0
- creat01deployengine/tracking/__init__.py +5 -0
- creat01deployengine/tracking/client.py +92 -0
- creat01deployengine/version.py +3 -0
- creat01deployengine-1.0.0.dist-info/METADATA +81 -0
- creat01deployengine-1.0.0.dist-info/RECORD +32 -0
- creat01deployengine-1.0.0.dist-info/WHEEL +4 -0
- creat01deployengine-1.0.0.dist-info/licenses/LICENSE +9 -0
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
# AI usage guide — Python
|
|
2
|
+
|
|
3
|
+
Use this decision order when generating code with `creat01deployengine`.
|
|
4
|
+
|
|
5
|
+
1. For management operations, read `DEPLOYENGINE_API_KEY` from the server
|
|
6
|
+
environment and create `DeployEngine` or `AsyncDeployEngine`.
|
|
7
|
+
2. For browser/application telemetry, use only `Tracker` with a project
|
|
8
|
+
`write_key`. Never substitute a management API key.
|
|
9
|
+
3. Prefer named resource methods over raw `client.request`.
|
|
10
|
+
4. For writes, provide an idempotency key when the method accepts one. Never
|
|
11
|
+
retry a payment, deployment, DNS, or infrastructure write blindly.
|
|
12
|
+
5. Catch typed errors and log `request_id`, but never log credentials.
|
|
13
|
+
|
|
14
|
+
## Method selection
|
|
15
|
+
|
|
16
|
+
```text
|
|
17
|
+
list/get/create/update/delete resource -> resource.list/get/create/update/delete
|
|
18
|
+
deployment validation -> projects.precheck
|
|
19
|
+
start deployment -> projects.deploy_stream
|
|
20
|
+
restart project -> projects.restart_stream
|
|
21
|
+
deployment/release history -> projects.deployments/releases
|
|
22
|
+
machine sizing -> machines.recommendations
|
|
23
|
+
Agent connectivity -> machines.agent_status
|
|
24
|
+
port connectivity -> machines.test_port
|
|
25
|
+
workflow state -> workflows.progress/detail
|
|
26
|
+
stop workflow -> workflows.terminate
|
|
27
|
+
upload/renew/deploy TLS -> certificates.upload/renew/deploy
|
|
28
|
+
DNS records -> domains.records/create_record/update_record/delete_record
|
|
29
|
+
sync load balancer -> load_balancers.sync
|
|
30
|
+
bind project to load balancer -> load_balancers.bind_project
|
|
31
|
+
add load-balancer listener -> load_balancers.add_listener
|
|
32
|
+
apply host firewall -> security_groups.apply
|
|
33
|
+
add firewall rule -> security_groups.add_rule
|
|
34
|
+
send alert -> alerts.send
|
|
35
|
+
create payment -> payments.create_order
|
|
36
|
+
refund payment -> payments.refund
|
|
37
|
+
send end-user login code -> authentication.send_code
|
|
38
|
+
login with code/password -> authentication.login_with_code/password_login
|
|
39
|
+
create customer feedback link -> feedback.create_ticket_link
|
|
40
|
+
tracking analytics/identity -> Tracker.track/identify
|
|
41
|
+
send application log -> LogReporter.debug/info/warning/error
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
`DeployEngine` methods return values immediately. The same resource methods on
|
|
45
|
+
`AsyncDeployEngine` must be awaited. Sync streams use `for`; async streams use
|
|
46
|
+
`async for`.
|
|
47
|
+
|
|
48
|
+
```python
|
|
49
|
+
import os
|
|
50
|
+
from creat01deployengine import AsyncDeployEngine
|
|
51
|
+
from creat01deployengine.errors import DeployEngineError
|
|
52
|
+
|
|
53
|
+
async def deploy(project_id: int, body: dict) -> None:
|
|
54
|
+
try:
|
|
55
|
+
async with AsyncDeployEngine(
|
|
56
|
+
api_key=os.environ["DEPLOYENGINE_API_KEY"]
|
|
57
|
+
) as client:
|
|
58
|
+
async for event in client.projects.deploy_stream(project_id, body):
|
|
59
|
+
print(event)
|
|
60
|
+
except DeployEngineError as exc:
|
|
61
|
+
print(exc.status_code, exc.code, exc.request_id)
|
|
62
|
+
raise
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Scopes: `read`, `deploy`, `machines`, `databases`, `certificates`,
|
|
66
|
+
`monitoring`, `infrastructure`, and `business`. A 403 means the key needs the
|
|
67
|
+
scope documented on the resource; do not work around it with a broader key in
|
|
68
|
+
client code.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
"""Public entry point for the Creat01 DeployEngine Python SDK.
|
|
2
|
+
|
|
3
|
+
Use :class:`DeployEngine` in synchronous applications and
|
|
4
|
+
:class:`AsyncDeployEngine` in asyncio services. Management clients require a
|
|
5
|
+
server-side API key or bearer token; browser-safe event ingestion uses
|
|
6
|
+
:class:`Tracker` instead.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from .client import AsyncDeployEngine, DeployEngine
|
|
10
|
+
from .errors import DeployEngineError
|
|
11
|
+
from .logging import LogReporter
|
|
12
|
+
from .tracking import Tracker
|
|
13
|
+
from .version import __version__
|
|
14
|
+
|
|
15
|
+
__all__ = [
|
|
16
|
+
"AsyncDeployEngine",
|
|
17
|
+
"DeployEngine",
|
|
18
|
+
"DeployEngineError",
|
|
19
|
+
"LogReporter",
|
|
20
|
+
"Tracker",
|
|
21
|
+
"__version__",
|
|
22
|
+
]
|
|
@@ -0,0 +1,276 @@
|
|
|
1
|
+
"""Authenticated HTTP clients shared by every management resource.
|
|
2
|
+
|
|
3
|
+
The clients unwrap DeployEngine's response envelope, attach request IDs, map
|
|
4
|
+
HTTP failures to typed exceptions, and retry only safe reads or writes carrying
|
|
5
|
+
an idempotency key. Most users should call a resource such as
|
|
6
|
+
``client.projects`` instead of :meth:`DeployEngine.request` directly.
|
|
7
|
+
"""
|
|
8
|
+
|
|
9
|
+
from __future__ import annotations
|
|
10
|
+
|
|
11
|
+
import random
|
|
12
|
+
import time
|
|
13
|
+
import uuid
|
|
14
|
+
from typing import Any
|
|
15
|
+
|
|
16
|
+
import httpx
|
|
17
|
+
|
|
18
|
+
from .errors import (
|
|
19
|
+
AuthenticationError,
|
|
20
|
+
ConflictError,
|
|
21
|
+
DeployEngineError,
|
|
22
|
+
NotFoundError,
|
|
23
|
+
PermissionDeniedError,
|
|
24
|
+
RateLimitError,
|
|
25
|
+
ValidationError,
|
|
26
|
+
)
|
|
27
|
+
from .version import __version__
|
|
28
|
+
|
|
29
|
+
_ERRORS = {
|
|
30
|
+
400: ValidationError,
|
|
31
|
+
401: AuthenticationError,
|
|
32
|
+
403: PermissionDeniedError,
|
|
33
|
+
404: NotFoundError,
|
|
34
|
+
409: ConflictError,
|
|
35
|
+
422: ValidationError,
|
|
36
|
+
429: RateLimitError,
|
|
37
|
+
}
|
|
38
|
+
_RETRYABLE = {429, 502, 503, 504}
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class _Base:
|
|
42
|
+
"""Internal configuration and response handling shared by both clients."""
|
|
43
|
+
|
|
44
|
+
def __init__(
|
|
45
|
+
self,
|
|
46
|
+
api_key: str | None = None,
|
|
47
|
+
*,
|
|
48
|
+
access_token: str | None = None,
|
|
49
|
+
base_url: str = "https://deployengine.creat01.com",
|
|
50
|
+
timeout: float = 30,
|
|
51
|
+
max_retries: int = 2,
|
|
52
|
+
):
|
|
53
|
+
"""Configure authentication, endpoint, timeout, and safe retry limits."""
|
|
54
|
+
if not api_key and not access_token:
|
|
55
|
+
raise ValueError("api_key or access_token is required")
|
|
56
|
+
self.base_url = base_url.rstrip("/")
|
|
57
|
+
self.timeout = timeout
|
|
58
|
+
self.max_retries = max(0, max_retries)
|
|
59
|
+
self.headers = {
|
|
60
|
+
"User-Agent": f"creat01deployengine-python/{__version__}",
|
|
61
|
+
"X-DeployEngine-SDK-Version": __version__,
|
|
62
|
+
}
|
|
63
|
+
self.headers["X-API-KEY" if api_key else "Authorization"] = (
|
|
64
|
+
api_key or f"Bearer {access_token}"
|
|
65
|
+
)
|
|
66
|
+
from .resources import install_resources
|
|
67
|
+
|
|
68
|
+
install_resources(self)
|
|
69
|
+
|
|
70
|
+
def _unwrap(self, response: httpx.Response) -> Any:
|
|
71
|
+
"""Return envelope data or raise the status-specific SDK exception."""
|
|
72
|
+
request_id = response.headers.get("X-Request-ID")
|
|
73
|
+
try:
|
|
74
|
+
body = response.json()
|
|
75
|
+
except ValueError:
|
|
76
|
+
body = {}
|
|
77
|
+
if not isinstance(body, dict):
|
|
78
|
+
body = {"data": body}
|
|
79
|
+
body_status = body.get("status_code", response.status_code)
|
|
80
|
+
if response.is_success and int(body_status) < 400:
|
|
81
|
+
return body.get("data") if "data" in body else body
|
|
82
|
+
status = (
|
|
83
|
+
response.status_code if response.status_code >= 400 else int(body_status)
|
|
84
|
+
)
|
|
85
|
+
cls = _ERRORS.get(status, DeployEngineError)
|
|
86
|
+
raise cls(
|
|
87
|
+
body.get("detail")
|
|
88
|
+
or body.get("message")
|
|
89
|
+
or response.text[:500]
|
|
90
|
+
or "DeployEngine request failed",
|
|
91
|
+
status_code=status,
|
|
92
|
+
code=body.get("code"),
|
|
93
|
+
request_id=request_id,
|
|
94
|
+
details=body.get("data"),
|
|
95
|
+
retryable=status in _RETRYABLE,
|
|
96
|
+
)
|
|
97
|
+
|
|
98
|
+
@staticmethod
|
|
99
|
+
def _can_retry(method: str, status: int, idempotency_key: str | None) -> bool:
|
|
100
|
+
"""Return whether a response can be retried without duplicating a write."""
|
|
101
|
+
return status in _RETRYABLE and (
|
|
102
|
+
method.upper() in {"GET", "HEAD"} or bool(idempotency_key)
|
|
103
|
+
)
|
|
104
|
+
|
|
105
|
+
|
|
106
|
+
class DeployEngine(_Base):
|
|
107
|
+
"""Synchronous management client.
|
|
108
|
+
|
|
109
|
+
Example::
|
|
110
|
+
|
|
111
|
+
with DeployEngine(api_key=os.environ["DEPLOYENGINE_API_KEY"]) as client:
|
|
112
|
+
projects = client.projects.list()
|
|
113
|
+
|
|
114
|
+
API keys must only be used in trusted server environments.
|
|
115
|
+
"""
|
|
116
|
+
|
|
117
|
+
def __init__(self, *args, **kwargs):
|
|
118
|
+
super().__init__(*args, **kwargs)
|
|
119
|
+
self._http = httpx.Client(
|
|
120
|
+
base_url=self.base_url, headers=self.headers, timeout=self.timeout
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
def request(
|
|
124
|
+
self,
|
|
125
|
+
method: str,
|
|
126
|
+
path: str,
|
|
127
|
+
*,
|
|
128
|
+
params=None,
|
|
129
|
+
json=None,
|
|
130
|
+
headers=None,
|
|
131
|
+
idempotency_key=None,
|
|
132
|
+
):
|
|
133
|
+
"""Send a management request and return unwrapped response data.
|
|
134
|
+
|
|
135
|
+
``path`` is relative to ``base_url``. GET/HEAD requests may retry;
|
|
136
|
+
writes retry only when ``idempotency_key`` is supplied. HTTP failures
|
|
137
|
+
raise :class:`~creat01deployengine.errors.DeployEngineError` subclasses.
|
|
138
|
+
"""
|
|
139
|
+
headers = {**(headers or {}), "X-Request-ID": str(uuid.uuid4())}
|
|
140
|
+
if idempotency_key:
|
|
141
|
+
headers["Idempotency-Key"] = idempotency_key
|
|
142
|
+
for attempt in range(self.max_retries + 1):
|
|
143
|
+
try:
|
|
144
|
+
response = self._http.request(
|
|
145
|
+
method, path, params=params, json=json, headers=headers
|
|
146
|
+
)
|
|
147
|
+
except httpx.TransportError:
|
|
148
|
+
if attempt == self.max_retries or (
|
|
149
|
+
method.upper() not in {"GET", "HEAD"} and not idempotency_key
|
|
150
|
+
):
|
|
151
|
+
raise
|
|
152
|
+
time.sleep((0.25 * 2**attempt) + random.random() * 0.1)
|
|
153
|
+
continue
|
|
154
|
+
if (
|
|
155
|
+
not self._can_retry(method, response.status_code, idempotency_key)
|
|
156
|
+
or attempt == self.max_retries
|
|
157
|
+
):
|
|
158
|
+
return self._unwrap(response)
|
|
159
|
+
time.sleep((0.25 * 2**attempt) + random.random() * 0.1)
|
|
160
|
+
|
|
161
|
+
def close(self):
|
|
162
|
+
"""Close the underlying connection pool."""
|
|
163
|
+
self._http.close()
|
|
164
|
+
|
|
165
|
+
def stream(self, method: str, path: str, *, json=None):
|
|
166
|
+
"""Yield decoded SSE payloads for deployment and maintenance streams.
|
|
167
|
+
|
|
168
|
+
JSON ``data:`` fields become Python objects; non-JSON fields remain
|
|
169
|
+
strings. The iterator owns and closes its HTTP response.
|
|
170
|
+
"""
|
|
171
|
+
import json as json_module
|
|
172
|
+
|
|
173
|
+
with self._http.stream(
|
|
174
|
+
method,
|
|
175
|
+
path,
|
|
176
|
+
json=json,
|
|
177
|
+
headers={"Accept": "text/event-stream", "X-Request-ID": str(uuid.uuid4())},
|
|
178
|
+
) as response:
|
|
179
|
+
response.raise_for_status()
|
|
180
|
+
for line in response.iter_lines():
|
|
181
|
+
if line.startswith("data:"):
|
|
182
|
+
value = line[5:].strip()
|
|
183
|
+
try:
|
|
184
|
+
yield json_module.loads(value)
|
|
185
|
+
except ValueError:
|
|
186
|
+
yield value
|
|
187
|
+
|
|
188
|
+
def __enter__(self):
|
|
189
|
+
"""Return this client from a synchronous context manager."""
|
|
190
|
+
return self
|
|
191
|
+
|
|
192
|
+
def __exit__(self, *_):
|
|
193
|
+
"""Close the client when leaving a synchronous context manager."""
|
|
194
|
+
self.close()
|
|
195
|
+
|
|
196
|
+
|
|
197
|
+
class AsyncDeployEngine(_Base):
|
|
198
|
+
"""Asyncio management client with the same resources as ``DeployEngine``.
|
|
199
|
+
|
|
200
|
+
Example::
|
|
201
|
+
|
|
202
|
+
async with AsyncDeployEngine(api_key=key) as client:
|
|
203
|
+
projects = await client.projects.list()
|
|
204
|
+
"""
|
|
205
|
+
|
|
206
|
+
def __init__(self, *args, **kwargs):
|
|
207
|
+
super().__init__(*args, **kwargs)
|
|
208
|
+
self._http = httpx.AsyncClient(
|
|
209
|
+
base_url=self.base_url, headers=self.headers, timeout=self.timeout
|
|
210
|
+
)
|
|
211
|
+
|
|
212
|
+
async def request(
|
|
213
|
+
self,
|
|
214
|
+
method: str,
|
|
215
|
+
path: str,
|
|
216
|
+
*,
|
|
217
|
+
params=None,
|
|
218
|
+
json=None,
|
|
219
|
+
headers=None,
|
|
220
|
+
idempotency_key=None,
|
|
221
|
+
):
|
|
222
|
+
"""Asynchronously send a request using the synchronous client's rules."""
|
|
223
|
+
import asyncio
|
|
224
|
+
|
|
225
|
+
headers = {**(headers or {}), "X-Request-ID": str(uuid.uuid4())}
|
|
226
|
+
if idempotency_key:
|
|
227
|
+
headers["Idempotency-Key"] = idempotency_key
|
|
228
|
+
for attempt in range(self.max_retries + 1):
|
|
229
|
+
try:
|
|
230
|
+
response = await self._http.request(
|
|
231
|
+
method, path, params=params, json=json, headers=headers
|
|
232
|
+
)
|
|
233
|
+
except httpx.TransportError:
|
|
234
|
+
if attempt == self.max_retries or (
|
|
235
|
+
method.upper() not in {"GET", "HEAD"} and not idempotency_key
|
|
236
|
+
):
|
|
237
|
+
raise
|
|
238
|
+
await asyncio.sleep((0.25 * 2**attempt) + random.random() * 0.1)
|
|
239
|
+
continue
|
|
240
|
+
if (
|
|
241
|
+
not self._can_retry(method, response.status_code, idempotency_key)
|
|
242
|
+
or attempt == self.max_retries
|
|
243
|
+
):
|
|
244
|
+
return self._unwrap(response)
|
|
245
|
+
await asyncio.sleep((0.25 * 2**attempt) + random.random() * 0.1)
|
|
246
|
+
|
|
247
|
+
async def close(self):
|
|
248
|
+
"""Close the asynchronous connection pool."""
|
|
249
|
+
await self._http.aclose()
|
|
250
|
+
|
|
251
|
+
async def stream(self, method: str, path: str, *, json=None):
|
|
252
|
+
"""Asynchronously yield decoded SSE ``data:`` payloads."""
|
|
253
|
+
import json as json_module
|
|
254
|
+
|
|
255
|
+
async with self._http.stream(
|
|
256
|
+
method,
|
|
257
|
+
path,
|
|
258
|
+
json=json,
|
|
259
|
+
headers={"Accept": "text/event-stream", "X-Request-ID": str(uuid.uuid4())},
|
|
260
|
+
) as response:
|
|
261
|
+
response.raise_for_status()
|
|
262
|
+
async for line in response.aiter_lines():
|
|
263
|
+
if line.startswith("data:"):
|
|
264
|
+
value = line[5:].strip()
|
|
265
|
+
try:
|
|
266
|
+
yield json_module.loads(value)
|
|
267
|
+
except ValueError:
|
|
268
|
+
yield value
|
|
269
|
+
|
|
270
|
+
async def __aenter__(self):
|
|
271
|
+
"""Return this client from an asynchronous context manager."""
|
|
272
|
+
return self
|
|
273
|
+
|
|
274
|
+
async def __aexit__(self, *_):
|
|
275
|
+
"""Close the client when leaving an asynchronous context manager."""
|
|
276
|
+
await self.close()
|
|
@@ -0,0 +1,51 @@
|
|
|
1
|
+
"""Typed failures raised by management-client requests.
|
|
2
|
+
|
|
3
|
+
Catch a specific subclass for recovery decisions or ``DeployEngineError`` for
|
|
4
|
+
all API failures. ``request_id`` should be included in support reports; never
|
|
5
|
+
include the API key itself.
|
|
6
|
+
"""
|
|
7
|
+
|
|
8
|
+
class DeployEngineError(Exception):
|
|
9
|
+
"""Base API error containing HTTP status and DeployEngine diagnostics."""
|
|
10
|
+
|
|
11
|
+
def __init__(
|
|
12
|
+
self,
|
|
13
|
+
message,
|
|
14
|
+
*,
|
|
15
|
+
status_code=0,
|
|
16
|
+
code=None,
|
|
17
|
+
request_id=None,
|
|
18
|
+
details=None,
|
|
19
|
+
retryable=False,
|
|
20
|
+
):
|
|
21
|
+
"""Store the message, status, machine code, request ID, and retry hint."""
|
|
22
|
+
super().__init__(message)
|
|
23
|
+
self.status_code = status_code
|
|
24
|
+
self.code = code
|
|
25
|
+
self.request_id = request_id
|
|
26
|
+
self.details = details
|
|
27
|
+
self.retryable = retryable
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
class AuthenticationError(DeployEngineError):
|
|
31
|
+
"""The API key or bearer token is missing, invalid, or expired (HTTP 401)."""
|
|
32
|
+
|
|
33
|
+
|
|
34
|
+
class PermissionDeniedError(DeployEngineError):
|
|
35
|
+
"""Authentication succeeded but the credential lacks the required scope."""
|
|
36
|
+
|
|
37
|
+
|
|
38
|
+
class NotFoundError(DeployEngineError):
|
|
39
|
+
"""The requested resource does not exist or is not visible to this user."""
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
class ValidationError(DeployEngineError):
|
|
43
|
+
"""The request body or query parameters failed validation (400 or 422)."""
|
|
44
|
+
|
|
45
|
+
|
|
46
|
+
class ConflictError(DeployEngineError):
|
|
47
|
+
"""The request conflicts with current resource state (HTTP 409)."""
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
class RateLimitError(DeployEngineError):
|
|
51
|
+
"""The request exceeded a server limit and may be retryable (HTTP 429)."""
|
|
@@ -0,0 +1,66 @@
|
|
|
1
|
+
"""Structured application-log adapter built on the tracking ingestion API."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
from ..tracking import Tracker
|
|
8
|
+
|
|
9
|
+
|
|
10
|
+
class LogReporter:
|
|
11
|
+
"""Report ``$log`` events with consistent service and environment context.
|
|
12
|
+
|
|
13
|
+
The reporter delegates delivery to a :class:`Tracker`; it does not accept or
|
|
14
|
+
expose a management API key.
|
|
15
|
+
"""
|
|
16
|
+
|
|
17
|
+
def __init__(
|
|
18
|
+
self,
|
|
19
|
+
tracker: Tracker,
|
|
20
|
+
*,
|
|
21
|
+
service: str | None = None,
|
|
22
|
+
environment: str | None = None,
|
|
23
|
+
):
|
|
24
|
+
"""Bind a tracker and optional service/environment labels."""
|
|
25
|
+
self.tracker, self.service, self.environment = tracker, service, environment
|
|
26
|
+
|
|
27
|
+
def log(
|
|
28
|
+
self,
|
|
29
|
+
level: str,
|
|
30
|
+
message: str,
|
|
31
|
+
*,
|
|
32
|
+
attributes: dict[str, Any] | None = None,
|
|
33
|
+
exception: dict[str, Any] | None = None,
|
|
34
|
+
trace_id: str | None = None,
|
|
35
|
+
user_id: str | None = None,
|
|
36
|
+
):
|
|
37
|
+
"""Report a structured log level, message, attributes, and trace context."""
|
|
38
|
+
return self.tracker.track(
|
|
39
|
+
"$log",
|
|
40
|
+
{
|
|
41
|
+
"level": level.upper(),
|
|
42
|
+
"message": message,
|
|
43
|
+
"service": self.service,
|
|
44
|
+
"environment": self.environment,
|
|
45
|
+
"trace_id": trace_id,
|
|
46
|
+
"attributes": attributes or {},
|
|
47
|
+
"exception": exception,
|
|
48
|
+
},
|
|
49
|
+
user_id=user_id,
|
|
50
|
+
)
|
|
51
|
+
|
|
52
|
+
def debug(self, message: str, **kwargs):
|
|
53
|
+
"""Report a DEBUG log event."""
|
|
54
|
+
return self.log("DEBUG", message, **kwargs)
|
|
55
|
+
|
|
56
|
+
def info(self, message: str, **kwargs):
|
|
57
|
+
"""Report an INFO log event."""
|
|
58
|
+
return self.log("INFO", message, **kwargs)
|
|
59
|
+
|
|
60
|
+
def warning(self, message: str, **kwargs):
|
|
61
|
+
"""Report a WARNING log event."""
|
|
62
|
+
return self.log("WARNING", message, **kwargs)
|
|
63
|
+
|
|
64
|
+
def error(self, message: str, **kwargs):
|
|
65
|
+
"""Report an ERROR log event."""
|
|
66
|
+
return self.log("ERROR", message, **kwargs)
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
"""Public type models importable from ``creat01deployengine.models``."""
|
|
2
|
+
|
|
3
|
+
from .common import Page
|
|
4
|
+
from .infrastructure import LoadBalancer, SecurityGroup, SecurityGroupRule
|
|
5
|
+
from .projects import CreateProjectRequest, Project
|
|
6
|
+
|
|
7
|
+
__all__ = [
|
|
8
|
+
"CreateProjectRequest",
|
|
9
|
+
"LoadBalancer",
|
|
10
|
+
"Page",
|
|
11
|
+
"Project",
|
|
12
|
+
"SecurityGroup",
|
|
13
|
+
"SecurityGroupRule",
|
|
14
|
+
]
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
"""Shared public model helpers used across SDK resource modules."""
|
|
2
|
+
|
|
3
|
+
from dataclasses import dataclass
|
|
4
|
+
from typing import Generic, TypeVar
|
|
5
|
+
|
|
6
|
+
T = TypeVar("T")
|
|
7
|
+
|
|
8
|
+
|
|
9
|
+
@dataclass(frozen=True, slots=True)
|
|
10
|
+
class Page(Generic[T]):
|
|
11
|
+
"""A page of ``items`` with one-based page metadata and a total count."""
|
|
12
|
+
|
|
13
|
+
items: list[T]
|
|
14
|
+
page: int
|
|
15
|
+
page_size: int
|
|
16
|
+
total: int
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""Typed mappings for load balancers, security groups, and firewall rules."""
|
|
2
|
+
|
|
3
|
+
from typing import NotRequired, TypedDict
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class LoadBalancer(TypedDict, total=False):
|
|
7
|
+
"""DeployEngine-managed load balancer summary."""
|
|
8
|
+
id: int
|
|
9
|
+
name: str
|
|
10
|
+
enabled: bool
|
|
11
|
+
gatewayMachineId: int
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class SecurityGroup(TypedDict, total=False):
|
|
15
|
+
"""Host firewall policy summary."""
|
|
16
|
+
id: int
|
|
17
|
+
name: str
|
|
18
|
+
description: str
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
class SecurityGroupRule(TypedDict):
|
|
22
|
+
"""Ingress or egress firewall rule accepted by security-group APIs."""
|
|
23
|
+
direction: str
|
|
24
|
+
protocol: str
|
|
25
|
+
portStart: NotRequired[int]
|
|
26
|
+
portEnd: NotRequired[int]
|
|
27
|
+
source: NotRequired[str]
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
"""Typed mappings for common project responses and create requests."""
|
|
2
|
+
|
|
3
|
+
from typing import NotRequired, TypedDict
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Project(TypedDict, total=False):
|
|
7
|
+
"""Project fields commonly returned by DeployEngine APIs."""
|
|
8
|
+
id: int
|
|
9
|
+
name: str
|
|
10
|
+
status: str
|
|
11
|
+
createdAt: str
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
class CreateProjectRequest(TypedDict):
|
|
15
|
+
"""Minimum supported request for creating a project."""
|
|
16
|
+
name: str
|
|
17
|
+
machineId: NotRequired[int]
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
"""Domain resource registry attached to synchronous and asynchronous clients.
|
|
2
|
+
|
|
3
|
+
Users access these objects as attributes such as ``client.projects`` and
|
|
4
|
+
``client.security_groups``; constructing them directly is unnecessary.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from .alerts import Alerts
|
|
8
|
+
from .authentication import Authentication
|
|
9
|
+
from .certificates import Certificates
|
|
10
|
+
from .domains import Domains
|
|
11
|
+
from .feedback import Feedback
|
|
12
|
+
from .load_balancers import LoadBalancers
|
|
13
|
+
from .machines import Machines
|
|
14
|
+
from .payments import Payments
|
|
15
|
+
from .projects import Projects
|
|
16
|
+
from .security_groups import SecurityGroups
|
|
17
|
+
from .tracking import Tracking
|
|
18
|
+
from .workflows import Workflows
|
|
19
|
+
|
|
20
|
+
|
|
21
|
+
def install_resources(client):
|
|
22
|
+
"""Attach every supported resource collection to ``client``."""
|
|
23
|
+
client.projects = Projects(client, "/api/projects")
|
|
24
|
+
client.machines = Machines(client, "/api/machines")
|
|
25
|
+
client.load_balancers = LoadBalancers(client, "/api/load-balancers")
|
|
26
|
+
client.security_groups = SecurityGroups(client, "/api/security-groups")
|
|
27
|
+
client.workflows = Workflows(client, "/api/workflow-tasks")
|
|
28
|
+
client.certificates = Certificates(client, "/api/certificates")
|
|
29
|
+
client.domains = Domains(client, "/api/domains")
|
|
30
|
+
client.alerts = Alerts(client, "/api/alert/contacts")
|
|
31
|
+
client.payments = Payments(client, "/api/orders")
|
|
32
|
+
client.authentication = Authentication(client, "/api/unified-login")
|
|
33
|
+
client.tracking = Tracking(client, "/api/tracking")
|
|
34
|
+
client.feedback = Feedback(client, "/api/feedback")
|
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
"""Alert-contact operations; management credentials require monitoring access."""
|
|
2
|
+
|
|
3
|
+
from .base import Resource
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Alerts(Resource):
|
|
7
|
+
"""List alert contacts and send test or operational notifications."""
|
|
8
|
+
|
|
9
|
+
def send(self, contact_id, data):
|
|
10
|
+
"""Send ``data`` through a contact identified by ``contact_id``."""
|
|
11
|
+
return self.client.request(
|
|
12
|
+
"POST", f"{self.prefix}/{contact_id}/send", json=data
|
|
13
|
+
)
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
"""Project-facing unified-login operations for the ``business`` scope."""
|
|
2
|
+
|
|
3
|
+
from .base import Resource
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Authentication(Resource):
|
|
7
|
+
"""Send verification codes and authenticate an end user for a project."""
|
|
8
|
+
|
|
9
|
+
def send_code(self, kind, project_name, identifier):
|
|
10
|
+
"""Send an SMS or email code.
|
|
11
|
+
|
|
12
|
+
``kind`` must be ``"sms"`` or ``"email"``; ``identifier`` is the
|
|
13
|
+
corresponding phone number or email address.
|
|
14
|
+
"""
|
|
15
|
+
return self.client.request(
|
|
16
|
+
"POST",
|
|
17
|
+
f"{self.prefix}/{kind}/send-code",
|
|
18
|
+
json={
|
|
19
|
+
"projectName": project_name,
|
|
20
|
+
"phone" if kind == "sms" else "email": identifier,
|
|
21
|
+
},
|
|
22
|
+
)
|
|
23
|
+
|
|
24
|
+
def login_with_code(self, kind, project_name, identifier, code):
|
|
25
|
+
"""Exchange an SMS/email verification code for a project login result."""
|
|
26
|
+
return self.client.request(
|
|
27
|
+
"POST",
|
|
28
|
+
f"{self.prefix}/{kind}/login",
|
|
29
|
+
json={
|
|
30
|
+
"projectName": project_name,
|
|
31
|
+
"phone" if kind == "sms" else "email": identifier,
|
|
32
|
+
"code": code,
|
|
33
|
+
},
|
|
34
|
+
)
|
|
35
|
+
|
|
36
|
+
def password_login(self, data):
|
|
37
|
+
"""Authenticate with the password-login request mapping in ``data``."""
|
|
38
|
+
return self.client.request("POST", f"{self.prefix}/password/login", json=data)
|
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
"""Generic CRUD operations inherited by domain resource collections."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from typing import Any
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class Resource:
|
|
9
|
+
"""Shared resource wiring and conventional list/get/create/update/delete calls.
|
|
10
|
+
|
|
11
|
+
Domain subclasses add explicit operations. Returned values are already
|
|
12
|
+
unwrapped from DeployEngine's ``{status_code, message, data}`` envelope.
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
def __init__(self, client: Any, prefix: str):
|
|
16
|
+
"""Bind a management client to an API path prefix."""
|
|
17
|
+
self.client = client
|
|
18
|
+
self.prefix = prefix
|
|
19
|
+
|
|
20
|
+
def list(self, **params):
|
|
21
|
+
"""List visible resources, forwarding keyword arguments as query params."""
|
|
22
|
+
return self.client.request("GET", self.prefix, params=params or None)
|
|
23
|
+
|
|
24
|
+
def get(self, resource_id):
|
|
25
|
+
"""Fetch one resource by numeric or string identifier."""
|
|
26
|
+
return self.client.request("GET", f"{self.prefix}/{resource_id}")
|
|
27
|
+
|
|
28
|
+
def create(self, data, *, idempotency_key=None):
|
|
29
|
+
"""Create a resource; pass an idempotency key to make retries safe."""
|
|
30
|
+
return self.client.request(
|
|
31
|
+
"POST", self.prefix, json=data, idempotency_key=idempotency_key
|
|
32
|
+
)
|
|
33
|
+
|
|
34
|
+
def update(self, resource_id, data):
|
|
35
|
+
"""Replace one resource using its API identifier and request mapping."""
|
|
36
|
+
return self.client.request("PUT", f"{self.prefix}/{resource_id}", json=data)
|
|
37
|
+
|
|
38
|
+
def delete(self, resource_id, *, confirm=True):
|
|
39
|
+
"""Delete one resource, sending the API's explicit confirmation flag."""
|
|
40
|
+
return self.client.request(
|
|
41
|
+
"DELETE",
|
|
42
|
+
f"{self.prefix}/{resource_id}",
|
|
43
|
+
params={"confirm": str(confirm).lower()},
|
|
44
|
+
)
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"""Certificate lifecycle operations requiring the ``certificates`` scope."""
|
|
2
|
+
|
|
3
|
+
from .base import Resource
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Certificates(Resource):
|
|
7
|
+
"""List certificates and perform upload, renewal, and deployment actions."""
|
|
8
|
+
|
|
9
|
+
def upload(self, data):
|
|
10
|
+
"""Upload certificate metadata and PEM content from ``data``."""
|
|
11
|
+
return self.client.request("POST", f"{self.prefix}/upload", json=data)
|
|
12
|
+
|
|
13
|
+
def renew(self, cert_id):
|
|
14
|
+
"""Request renewal of certificate ``cert_id``; this has external effects."""
|
|
15
|
+
return self.client.request("POST", f"{self.prefix}/{cert_id}/renew")
|
|
16
|
+
|
|
17
|
+
def deploy(self, cert_id, data):
|
|
18
|
+
"""Deploy certificate ``cert_id`` according to target mapping ``data``."""
|
|
19
|
+
return self.client.request("POST", f"{self.prefix}/{cert_id}/deploy", json=data)
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
"""DNS zone and record operations exposed by DeployEngine."""
|
|
2
|
+
|
|
3
|
+
from .base import Resource
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Domains(Resource):
|
|
7
|
+
"""Manage DNS records visible to the authenticated account."""
|
|
8
|
+
|
|
9
|
+
def records(self, **params):
|
|
10
|
+
"""List DNS records, forwarding filters and pagination as query params."""
|
|
11
|
+
return self.client.request(
|
|
12
|
+
"GET", f"{self.prefix}/records", params=params or None
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
def create_record(self, data):
|
|
16
|
+
"""Create a DNS record from the API request mapping ``data``."""
|
|
17
|
+
return self.client.request("POST", f"{self.prefix}/records", json=data)
|
|
18
|
+
|
|
19
|
+
def update_record(self, record_id, data):
|
|
20
|
+
"""Update DNS record ``record_id`` using fields in ``data``."""
|
|
21
|
+
return self.client.request(
|
|
22
|
+
"PUT", f"{self.prefix}/records/{record_id}", json=data
|
|
23
|
+
)
|
|
24
|
+
|
|
25
|
+
def delete_record(self, record_id):
|
|
26
|
+
"""Permanently delete DNS record ``record_id``."""
|
|
27
|
+
return self.client.request("DELETE", f"{self.prefix}/records/{record_id}")
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"""Customer-feedback link operations in the ``business`` capability."""
|
|
2
|
+
|
|
3
|
+
from .base import Resource
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Feedback(Resource):
|
|
7
|
+
"""Create short-lived links through which customers can submit feedback."""
|
|
8
|
+
|
|
9
|
+
def create_ticket_link(self, project_id=None):
|
|
10
|
+
"""Create a feedback ticket link, optionally scoped to ``project_id``."""
|
|
11
|
+
return self.client.request(
|
|
12
|
+
"POST",
|
|
13
|
+
f"{self.prefix}/ticket-link",
|
|
14
|
+
params={"projectId": project_id} if project_id else None,
|
|
15
|
+
)
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
"""DeployEngine-managed load balancer operations (``infrastructure`` scope)."""
|
|
2
|
+
|
|
3
|
+
from .base import Resource
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class LoadBalancers(Resource):
|
|
7
|
+
"""Configure gateways, project bindings, listeners, and remote sync."""
|
|
8
|
+
|
|
9
|
+
def update(self, resource_id, data):
|
|
10
|
+
"""Partially update load balancer ``resource_id`` from ``data``."""
|
|
11
|
+
return self.client.request("PATCH", f"{self.prefix}/{resource_id}", json=data)
|
|
12
|
+
|
|
13
|
+
def sync(self, resource_id):
|
|
14
|
+
"""Synchronize configuration to the gateway using a stable retry key."""
|
|
15
|
+
return self.client.request(
|
|
16
|
+
"POST",
|
|
17
|
+
f"{self.prefix}/{resource_id}/sync",
|
|
18
|
+
idempotency_key=f"lb-sync-{resource_id}",
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
def bind_project(self, resource_id, project_id, binding_spec=None):
|
|
22
|
+
"""Bind ``project_id`` to a load balancer with an optional binding spec."""
|
|
23
|
+
return self.client.request(
|
|
24
|
+
"POST",
|
|
25
|
+
f"{self.prefix}/{resource_id}/projects",
|
|
26
|
+
json={"projectId": project_id, "bindingSpec": binding_spec or {}},
|
|
27
|
+
)
|
|
28
|
+
|
|
29
|
+
def add_listener(self, resource_id, data):
|
|
30
|
+
"""Add a listener to load balancer ``resource_id`` from ``data``."""
|
|
31
|
+
return self.client.request(
|
|
32
|
+
"POST", f"{self.prefix}/{resource_id}/listeners", json=data
|
|
33
|
+
)
|
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
"""Machine inventory and diagnostics operations (``machines`` scope)."""
|
|
2
|
+
|
|
3
|
+
from .base import Resource
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Machines(Resource):
|
|
7
|
+
"""Manage machines and inspect connectivity or Agent availability."""
|
|
8
|
+
|
|
9
|
+
def recommendations(self, data):
|
|
10
|
+
"""Return machine recommendations for workload requirements in ``data``."""
|
|
11
|
+
return self.client.request("POST", "/api/machines/recommendations", json=data)
|
|
12
|
+
|
|
13
|
+
def agent_status(self, machine_id):
|
|
14
|
+
"""Return the current DeployEngine Agent status for ``machine_id``."""
|
|
15
|
+
return self.client.request("GET", f"/api/machines/{machine_id}/agent/status")
|
|
16
|
+
|
|
17
|
+
def test_port(self, machine_id, port):
|
|
18
|
+
"""Test whether TCP ``port`` is reachable on ``machine_id``."""
|
|
19
|
+
return self.client.request(
|
|
20
|
+
"POST", f"/api/machines/{machine_id}/test-port", json={"port": port}
|
|
21
|
+
)
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
"""Unified-payment order operations requiring the ``business`` scope."""
|
|
2
|
+
|
|
3
|
+
from .base import Resource
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Payments(Resource):
|
|
7
|
+
"""Create payment orders and request refunds through configured providers."""
|
|
8
|
+
|
|
9
|
+
def create_order(self, data, *, idempotency_key=None):
|
|
10
|
+
"""Create an order from ``data``.
|
|
11
|
+
|
|
12
|
+
Supply a unique ``idempotency_key`` for safe network retries; reuse it
|
|
13
|
+
only for the same logical order.
|
|
14
|
+
"""
|
|
15
|
+
return self.client.request(
|
|
16
|
+
"POST", "/api/orders/create_v2", json=data, idempotency_key=idempotency_key
|
|
17
|
+
)
|
|
18
|
+
|
|
19
|
+
def refund(self, order_no, refund_fee, reason=None):
|
|
20
|
+
"""Refund ``refund_fee`` for ``order_no`` with an optional reason."""
|
|
21
|
+
return self.client.request(
|
|
22
|
+
"POST",
|
|
23
|
+
f"/api/orders/{order_no}/refund",
|
|
24
|
+
json={"refundFee": refund_fee, "reason": reason},
|
|
25
|
+
)
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""Project, deployment, and release operations (``deploy`` or ``read`` scope)."""
|
|
2
|
+
|
|
3
|
+
from .base import Resource
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Projects(Resource):
|
|
7
|
+
"""Manage projects and run deployment workflows."""
|
|
8
|
+
|
|
9
|
+
def precheck(self, project_id, data):
|
|
10
|
+
"""Validate deployment inputs for ``project_id`` without deploying."""
|
|
11
|
+
return self.client.request(
|
|
12
|
+
"POST", f"/api/projects/{project_id}/deploy-precheck", json=data
|
|
13
|
+
)
|
|
14
|
+
|
|
15
|
+
def deployments(self, project_id):
|
|
16
|
+
"""List deployment records belonging to ``project_id``."""
|
|
17
|
+
return self.client.request("GET", f"/api/projects/{project_id}/deployments")
|
|
18
|
+
|
|
19
|
+
def releases(self, project_id):
|
|
20
|
+
"""List release-history records belonging to ``project_id``."""
|
|
21
|
+
return self.client.request("GET", f"/api/projects/{project_id}/release-history")
|
|
22
|
+
|
|
23
|
+
def deploy_stream(self, project_id, data):
|
|
24
|
+
"""Return an SSE iterator for a new deployment.
|
|
25
|
+
|
|
26
|
+
Iteration starts a side-effecting deployment. Consume every event to
|
|
27
|
+
observe success or failure; stream events are decoded JSON when valid.
|
|
28
|
+
"""
|
|
29
|
+
return self.client.stream(
|
|
30
|
+
"POST", f"/api/projects/{project_id}/deploy-stream", json=data
|
|
31
|
+
)
|
|
32
|
+
|
|
33
|
+
def restart_stream(self, project_id, data=None):
|
|
34
|
+
"""Return an SSE iterator while restarting a deployed project."""
|
|
35
|
+
return self.client.stream(
|
|
36
|
+
"POST", f"/api/projects/{project_id}/restart-stream", json=data or {}
|
|
37
|
+
)
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
"""Host firewall policy operations requiring ``infrastructure`` scope."""
|
|
2
|
+
|
|
3
|
+
from .base import Resource
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class SecurityGroups(Resource):
|
|
7
|
+
"""Manage DeployEngine nftables security groups and their rules."""
|
|
8
|
+
|
|
9
|
+
def update(self, resource_id, data):
|
|
10
|
+
"""Partially update security group ``resource_id`` from ``data``."""
|
|
11
|
+
return self.client.request("PATCH", f"{self.prefix}/{resource_id}", json=data)
|
|
12
|
+
|
|
13
|
+
def apply(self, resource_id):
|
|
14
|
+
"""Apply a group to associated machines using a stable retry key."""
|
|
15
|
+
return self.client.request(
|
|
16
|
+
"POST",
|
|
17
|
+
f"{self.prefix}/{resource_id}/apply",
|
|
18
|
+
idempotency_key=f"sg-apply-{resource_id}",
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
def add_rule(self, resource_id, data):
|
|
22
|
+
"""Add a rule; ``data.idempotencyKey`` enables safe write retries."""
|
|
23
|
+
return self.client.request(
|
|
24
|
+
"POST",
|
|
25
|
+
f"{self.prefix}/{resource_id}/rules",
|
|
26
|
+
json=data,
|
|
27
|
+
idempotency_key=data.get("idempotencyKey"),
|
|
28
|
+
)
|
|
@@ -0,0 +1,37 @@
|
|
|
1
|
+
"""Low-level tracking ingestion for project-scoped write keys."""
|
|
2
|
+
|
|
3
|
+
from uuid import uuid4
|
|
4
|
+
|
|
5
|
+
from .base import Resource
|
|
6
|
+
|
|
7
|
+
|
|
8
|
+
class Tracking(Resource):
|
|
9
|
+
"""Send event batches or identity links without exposing management keys."""
|
|
10
|
+
|
|
11
|
+
def collect(self, app_id, project_name, write_key, events):
|
|
12
|
+
"""Ingest an event list for an application using its browser-safe key."""
|
|
13
|
+
return self.client.request(
|
|
14
|
+
"POST",
|
|
15
|
+
f"{self.prefix}/v1/collect",
|
|
16
|
+
headers={"X-Write-Key": write_key},
|
|
17
|
+
json={"app_id": app_id, "project_name": project_name, "events": events},
|
|
18
|
+
idempotency_key=f"tracking-{app_id}-{uuid4()}",
|
|
19
|
+
)
|
|
20
|
+
|
|
21
|
+
def identify(
|
|
22
|
+
self, app_id, project_name, write_key, anonymous_id, user_id, traits=None
|
|
23
|
+
):
|
|
24
|
+
"""Associate ``anonymous_id`` with ``user_id`` and optional traits."""
|
|
25
|
+
return self.client.request(
|
|
26
|
+
"POST",
|
|
27
|
+
f"{self.prefix}/v1/identify",
|
|
28
|
+
headers={"X-Write-Key": write_key},
|
|
29
|
+
json={
|
|
30
|
+
"app_id": app_id,
|
|
31
|
+
"project_name": project_name,
|
|
32
|
+
"anonymous_id": anonymous_id,
|
|
33
|
+
"user_id": user_id,
|
|
34
|
+
"traits": traits or {},
|
|
35
|
+
},
|
|
36
|
+
idempotency_key=f"identify-{app_id}-{anonymous_id}",
|
|
37
|
+
)
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
"""Workflow task inspection and termination operations."""
|
|
2
|
+
|
|
3
|
+
from .base import Resource
|
|
4
|
+
|
|
5
|
+
|
|
6
|
+
class Workflows(Resource):
|
|
7
|
+
"""Read workflow progress/details and terminate eligible tasks."""
|
|
8
|
+
|
|
9
|
+
def progress(self, task_id):
|
|
10
|
+
"""Return summarized progress for workflow ``task_id``."""
|
|
11
|
+
return self.client.request("GET", f"{self.prefix}/{task_id}/progress")
|
|
12
|
+
|
|
13
|
+
def detail(self, task_id):
|
|
14
|
+
"""Return detailed workflow steps and diagnostic output."""
|
|
15
|
+
return self.client.request("GET", f"{self.prefix}/{task_id}/detail")
|
|
16
|
+
|
|
17
|
+
def terminate(self, task_id):
|
|
18
|
+
"""Request termination of a running workflow; completion is asynchronous."""
|
|
19
|
+
return self.client.request("POST", f"{self.prefix}/{task_id}/terminate")
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
"""Browser-safe style event tracker backed by a project-scoped write key."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
from datetime import datetime, timezone
|
|
6
|
+
from typing import Any
|
|
7
|
+
from uuid import uuid4
|
|
8
|
+
|
|
9
|
+
import httpx
|
|
10
|
+
|
|
11
|
+
|
|
12
|
+
class Tracker:
|
|
13
|
+
"""Send analytics events without a DeployEngine management credential.
|
|
14
|
+
|
|
15
|
+
``write_key`` is limited to ingestion for ``app_id``. Use a context manager
|
|
16
|
+
to release the underlying HTTP connection when the tracker is no longer used.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
def __init__(
|
|
20
|
+
self,
|
|
21
|
+
*,
|
|
22
|
+
app_id: str,
|
|
23
|
+
project_name: str,
|
|
24
|
+
write_key: str,
|
|
25
|
+
base_url: str = "https://deployengine.creat01.com",
|
|
26
|
+
timeout: float = 10,
|
|
27
|
+
):
|
|
28
|
+
"""Configure the application identity, ingestion key, endpoint, and timeout."""
|
|
29
|
+
self.app_id, self.project_name = app_id, project_name
|
|
30
|
+
self.anonymous_id = str(uuid4())
|
|
31
|
+
self._http = httpx.Client(
|
|
32
|
+
base_url=base_url.rstrip("/"),
|
|
33
|
+
headers={"X-Write-Key": write_key},
|
|
34
|
+
timeout=timeout,
|
|
35
|
+
)
|
|
36
|
+
|
|
37
|
+
def track(
|
|
38
|
+
self,
|
|
39
|
+
event: str,
|
|
40
|
+
properties: dict[str, Any] | None = None,
|
|
41
|
+
*,
|
|
42
|
+
user_id: str | None = None,
|
|
43
|
+
anonymous_id: str | None = None,
|
|
44
|
+
):
|
|
45
|
+
"""Send one named event with optional properties and user identity."""
|
|
46
|
+
item = {
|
|
47
|
+
"event_name": event,
|
|
48
|
+
"properties": properties or {},
|
|
49
|
+
"user_id": user_id,
|
|
50
|
+
"anonymous_id": anonymous_id or self.anonymous_id,
|
|
51
|
+
"timestamp": datetime.now(timezone.utc).isoformat(),
|
|
52
|
+
"message_id": str(uuid4()),
|
|
53
|
+
}
|
|
54
|
+
response = self._http.post(
|
|
55
|
+
"/api/tracking/v1/collect",
|
|
56
|
+
json={
|
|
57
|
+
"app_id": self.app_id,
|
|
58
|
+
"project_name": self.project_name,
|
|
59
|
+
"events": [item],
|
|
60
|
+
},
|
|
61
|
+
)
|
|
62
|
+
response.raise_for_status()
|
|
63
|
+
return response.json().get("data")
|
|
64
|
+
|
|
65
|
+
def identify(
|
|
66
|
+
self, anonymous_id: str, user_id: str, traits: dict[str, Any] | None = None
|
|
67
|
+
):
|
|
68
|
+
"""Link a prior anonymous identity to an application user and traits."""
|
|
69
|
+
response = self._http.post(
|
|
70
|
+
"/api/tracking/v1/identify",
|
|
71
|
+
json={
|
|
72
|
+
"app_id": self.app_id,
|
|
73
|
+
"project_name": self.project_name,
|
|
74
|
+
"anonymous_id": anonymous_id,
|
|
75
|
+
"user_id": user_id,
|
|
76
|
+
"traits": traits or {},
|
|
77
|
+
},
|
|
78
|
+
)
|
|
79
|
+
response.raise_for_status()
|
|
80
|
+
return response.json().get("data")
|
|
81
|
+
|
|
82
|
+
def close(self):
|
|
83
|
+
"""Close the tracker's HTTP connection pool."""
|
|
84
|
+
self._http.close()
|
|
85
|
+
|
|
86
|
+
def __enter__(self):
|
|
87
|
+
"""Return this tracker from a context manager."""
|
|
88
|
+
return self
|
|
89
|
+
|
|
90
|
+
def __exit__(self, *_):
|
|
91
|
+
"""Close the tracker when leaving a context manager."""
|
|
92
|
+
self.close()
|
|
@@ -0,0 +1,81 @@
|
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
|
+
Name: creat01deployengine
|
|
3
|
+
Version: 1.0.0
|
|
4
|
+
Summary: Official Python SDK for Creat01 DeployEngine
|
|
5
|
+
License-Expression: MIT
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
Classifier: Development Status :: 4 - Beta
|
|
8
|
+
Classifier: Programming Language :: Python :: 3
|
|
9
|
+
Classifier: Typing :: Typed
|
|
10
|
+
Requires-Python: >=3.9
|
|
11
|
+
Requires-Dist: httpx<1,>=0.27
|
|
12
|
+
Provides-Extra: test
|
|
13
|
+
Requires-Dist: pytest-asyncio>=0.24; extra == 'test'
|
|
14
|
+
Requires-Dist: pytest>=8; extra == 'test'
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
|
|
17
|
+
# creat01deployengine Python SDK
|
|
18
|
+
|
|
19
|
+
Official synchronous and asynchronous clients for the DeployEngine API.
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
python -m pip install creat01deployengine
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Use `DeployEngine` in synchronous code, `AsyncDeployEngine` in asyncio code,
|
|
26
|
+
and `Tracker`/`LogReporter` for application-side event ingestion. Never ship a
|
|
27
|
+
management API key in browser, desktop, or mobile code.
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
import os
|
|
31
|
+
from creat01deployengine import DeployEngine
|
|
32
|
+
from creat01deployengine.errors import PermissionDeniedError
|
|
33
|
+
|
|
34
|
+
try:
|
|
35
|
+
with DeployEngine(
|
|
36
|
+
api_key=os.environ["DEPLOYENGINE_API_KEY"],
|
|
37
|
+
base_url="https://deployengine.creat01.com",
|
|
38
|
+
) as client:
|
|
39
|
+
projects = client.projects.list(page=1, pageSize=20)
|
|
40
|
+
machine = client.machines.get(12)
|
|
41
|
+
except PermissionDeniedError as exc:
|
|
42
|
+
print(f"missing API scope; request={exc.request_id}")
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
```python
|
|
46
|
+
from creat01deployengine import AsyncDeployEngine
|
|
47
|
+
|
|
48
|
+
async with AsyncDeployEngine(api_key=key) as client:
|
|
49
|
+
projects = await client.projects.list()
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
## Resource map
|
|
53
|
+
|
|
54
|
+
| Attribute | Purpose | Typical scope |
|
|
55
|
+
|---|---|---|
|
|
56
|
+
| `projects` | CRUD, precheck, deployments, releases, deploy/restart streams | `read`, `deploy` |
|
|
57
|
+
| `machines` | CRUD, recommendations, Agent state, port checks | `machines` |
|
|
58
|
+
| `workflows` | Task progress, detail, termination | `read`, `deploy` |
|
|
59
|
+
| `certificates` | CRUD, upload, renewal, deployment | `certificates` |
|
|
60
|
+
| `domains` | Domain CRUD and DNS records | `read` |
|
|
61
|
+
| `load_balancers` | Gateway config, sync, bindings, listeners | `infrastructure` |
|
|
62
|
+
| `security_groups` | Host firewall policy, apply, rules | `infrastructure` |
|
|
63
|
+
| `alerts` | Alert contacts and notification sending | `monitoring` |
|
|
64
|
+
| `payments` | Payment orders and refunds | `business` |
|
|
65
|
+
| `authentication` | Project SMS/email/password login | `business` |
|
|
66
|
+
| `feedback` | Customer feedback ticket links | `business` |
|
|
67
|
+
| `tracking` | Low-level event ingestion | tracking write key |
|
|
68
|
+
|
|
69
|
+
```python
|
|
70
|
+
with DeployEngine(api_key=key) as client:
|
|
71
|
+
for event in client.projects.deploy_stream(7, {"branch": "main"}):
|
|
72
|
+
print(event)
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Resources return the unwrapped `data` field. Writes are not retried unless an
|
|
76
|
+
idempotency key is present. `DeployEngineError` exposes `status_code`, `code`,
|
|
77
|
+
`request_id`, `details`, and `retryable`. See `AI_USAGE.md` for task recipes.
|
|
78
|
+
|
|
79
|
+
Maintainers can run the opt-in live smoke test with
|
|
80
|
+
`DEPLOYENGINE_E2E_API_KEY=... pytest tests/test_live_api.py`. It performs only
|
|
81
|
+
authenticated list operations and does not deploy or mutate resources.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
creat01deployengine/__init__.py,sha256=vOMt9aushUiHlnQc1386UcKwJOU3K8BzF4hdUzxRXe8,625
|
|
2
|
+
creat01deployengine/client.py,sha256=FNvRosVAgz4BQmZ35EsCXwEKy7bhp5sjb8Vw0mRnUq4,9342
|
|
3
|
+
creat01deployengine/errors.py,sha256=sb1WAaK3Kx3yWcnz16Y1NWVoc_kE4vRtVew8na0PLms,1567
|
|
4
|
+
creat01deployengine/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
|
|
5
|
+
creat01deployengine/version.py,sha256=boMX9vTVAkTuel0zMJwQhhFCUtAxLcOipNl9H2jifPk,94
|
|
6
|
+
creat01deployengine/logging/__init__.py,sha256=-UlR2DHbE3xgUT0knwILR77x8xGisFM_VwJXLQrJTBo,131
|
|
7
|
+
creat01deployengine/logging/reporter.py,sha256=hGEo8_TtMw9RHhuHZp9cYbh14SCCjTTFtOu2rCUWhZ0,2018
|
|
8
|
+
creat01deployengine/models/__init__.py,sha256=MLePJO-P9kQ8f106v1HY6PvYy5yLjN41IROREQmtpO8,362
|
|
9
|
+
creat01deployengine/models/common.py,sha256=Qgof4BwNLCR2BASrSkrI5nz7eq_11EEYRMSFiEMCAdw,365
|
|
10
|
+
creat01deployengine/models/infrastructure.py,sha256=qRxkm2CXVD1on87ncteLZcp14b1OXH3cj5uNFAjb1fc,666
|
|
11
|
+
creat01deployengine/models/projects.py,sha256=QV6nSOMscmpHdqXDopl1uXvaZOPVIajxvAJuqHs19Po,428
|
|
12
|
+
creat01deployengine/resources/__init__.py,sha256=fMp6vD0rdNKfu1arIxf4bRH6XYU1Q2JXpvAFhNiiQfY,1484
|
|
13
|
+
creat01deployengine/resources/alerts.py,sha256=fPYPPD0XSuI2XANJ6KPk_3eezvEW2RGiPf_qS_L5eNw,437
|
|
14
|
+
creat01deployengine/resources/authentication.py,sha256=9diSUiQMP2Gu9xLCskqDehYjhoe6UzMG_k3ct2LBJMA,1349
|
|
15
|
+
creat01deployengine/resources/base.py,sha256=N8Q9OTURD5i7kGvLPT6ugKOfdpocFqqF0e7i10_VtR8,1695
|
|
16
|
+
creat01deployengine/resources/certificates.py,sha256=_3Y0X3Wn_nqxGBs8ozJCL_PKTtEmjJ74jhORrlkd6ew,802
|
|
17
|
+
creat01deployengine/resources/domains.py,sha256=8r7-s62kDKQ-oMmBmT6LUMjnI4OS5yTgN_vUIMpu8Pk,1018
|
|
18
|
+
creat01deployengine/resources/feedback.py,sha256=LOT_XQZoJ6v10flNj6nk3waJKZjsfEVEMA3tjM16JPg,520
|
|
19
|
+
creat01deployengine/resources/load_balancers.py,sha256=gErbv6CVvoZ0HRavJ2AGI_Qmvb9SjJghManRm6smI0I,1304
|
|
20
|
+
creat01deployengine/resources/machines.py,sha256=BTpjjZG958Gs0TebRuwD44JzFi_LpZQUlgGQ4jhvT-8,861
|
|
21
|
+
creat01deployengine/resources/payments.py,sha256=KUoCjWhWwdPDpyJ1Z6sxfIUneG4B28xqkXq6WzkRvfM,890
|
|
22
|
+
creat01deployengine/resources/projects.py,sha256=3Jr6DTL2XhzcJMwACVsqKp5_f-xO5imAdzrJrWDaOfQ,1477
|
|
23
|
+
creat01deployengine/resources/security_groups.py,sha256=7ZX6XuVoDsbNEbxPldpz_VLMMiAXSOe8_mdRhdhEnoU,1014
|
|
24
|
+
creat01deployengine/resources/tracking.py,sha256=u7E0_bF2uJNmB6Xno5EJNGJQbEWfs6YxA3sJmJ79yw4,1318
|
|
25
|
+
creat01deployengine/resources/workflows.py,sha256=zsAxbutAh6AAMRQGVDkFuVRNSLNaxlU_ncQ7yiUnN-M,745
|
|
26
|
+
creat01deployengine/tracking/__init__.py,sha256=CDr0MDBQbB_ndj018xKSPtkg3NkPUwlGS2ZN99FMsc4,129
|
|
27
|
+
creat01deployengine/tracking/client.py,sha256=b8mnAmOjVpRj7btPQ7zPD3KN4dP-77cdfWUhaDNiJ3M,2872
|
|
28
|
+
creat01deployengine/AI_USAGE.md,sha256=yntpjq7ll9Ujv4a7U55u0E1yoIBqLCnQZWTCuc9ZBL0,3314
|
|
29
|
+
creat01deployengine-1.0.0.dist-info/METADATA,sha256=qgVXkQWVWN04X3zUbmAqdrHaLVSgO2y8Oq-Z5c5Xn_Y,3025
|
|
30
|
+
creat01deployengine-1.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
|
|
31
|
+
creat01deployengine-1.0.0.dist-info/licenses/LICENSE,sha256=nSiH5jSOHHGPZs_XIEceNIK-Mmt_0JglPAxnkVaCshw,1064
|
|
32
|
+
creat01deployengine-1.0.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Creat01
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
|
|
6
|
+
|
|
7
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
|
|
8
|
+
|
|
9
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|