system-design-primer-skill 1.2.0 → 2.4.0
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.
- package/README.md +114 -60
- package/SKILL.md +437 -93
- package/VERSION +1 -1
- package/evals/README.md +1022 -0
- package/evals/system-design-cases.json +414 -0
- package/package.json +46 -4
- package/references/03-data-and-storage.md +8 -2
- package/references/04-caching.md +3 -3
- package/references/05-async-and-messaging.md +4 -0
- package/references/06-distributed-systems.md +2 -2
- package/references/07-reliability-and-resilience.md +7 -3
- package/references/08-api-security-observability.md +4 -0
- package/references/10-workflows-and-checklists.md +1 -1
- package/references/13-architecture-intelligence.md +91 -0
- package/references/14-api-and-data-contracts.md +80 -0
- package/references/15-failure-analysis.md +88 -0
- package/references/16-multi-agent-architecture.md +76 -0
- package/references/17-agent-harness-and-runtime.md +87 -0
- package/references/18-mcp-architecture.md +67 -0
- package/references/19-agent-security-and-permissions.md +90 -0
- package/references/20-agent-state-and-memory.md +76 -0
- package/references/21-agent-evaluation-and-observability.md +90 -0
- package/references/22-kubernetes-and-container-platforms.md +29 -0
- package/references/23-service-mesh-and-traffic-management.md +21 -0
- package/references/24-multi-region-and-disaster-recovery.md +28 -0
- package/references/25-platform-engineering-and-developer-experience.md +26 -0
- package/references/26-finops-and-cloud-cost.md +29 -0
- package/references/27-production-observability-and-slo.md +33 -0
- package/references/28-event-streaming-and-kafka-pulsar.md +33 -0
- package/references/29-event-sourcing-and-cqrs.md +23 -0
- package/references/30-change-data-capture-and-debezium.md +27 -0
- package/references/31-data-lakehouse-and-stream-batch.md +24 -0
- package/references/32-workflow-orchestration-and-temporal.md +28 -0
- package/references/33-schema-registry-and-event-governance.md +22 -0
- package/references/34-postgresql-internals-and-performance.md +45 -0
- package/references/35-mysql-innodb-and-performance.md +29 -0
- package/references/36-sharding-and-distributed-sql.md +22 -0
- package/references/37-consensus-and-distributed-transactions.md +29 -0
- package/references/38-search-architecture-elasticsearch-opensearch.md +24 -0
- package/references/39-vector-databases-and-hybrid-retrieval.md +31 -0
- package/references/40-zero-downtime-database-migrations.md +27 -0
- package/references/41-api-gateway-and-edge-architecture.md +23 -0
- package/references/42-rest-api-design-and-lifecycle.md +23 -0
- package/references/43-graphql-architecture-and-governance.md +16 -0
- package/references/44-grpc-and-service-contracts.md +16 -0
- package/references/45-websocket-sse-and-realtime-systems.md +16 -0
- package/references/46-realtime-collaboration-ot-crdt.md +16 -0
- package/references/47-api-security-rate-limiting-and-abuse.md +16 -0
- package/references/48-oauth-oidc-and-passkeys.md +20 -0
- package/references/49-iam-rbac-abac-rebac.md +20 -0
- package/references/50-zero-trust-and-workload-identity.md +16 -0
- package/references/51-secrets-kms-pki-and-key-management.md +20 -0
- package/references/52-supply-chain-security-sbom-slsa.md +78 -0
- package/references/53-threat-modeling-stride-and-attack-trees.md +16 -0
- package/references/54-privacy-engineering-and-data-governance.md +20 -0
- package/references/55-opentelemetry-and-instrumentation.md +54 -0
- package/references/56-distributed-tracing-and-context-propagation.md +47 -0
- package/references/57-continuous-profiling-and-performance-diagnostics.md +45 -0
- package/references/58-load-stress-soak-testing-and-workload-modeling.md +44 -0
- package/references/59-capacity-planning-and-performance-modeling.md +38 -0
- package/references/60-chaos-engineering-and-resilience-experiments.md +45 -0
- package/references/61-incident-management-and-postmortems.md +38 -0
- package/references/62-dns-and-service-discovery.md +35 -0
- package/references/63-load-balancing-and-global-traffic-management.md +31 -0
- package/references/64-cdn-and-edge-caching.md +34 -0
- package/references/65-cloud-networking-and-connectivity.md +34 -0
- package/references/66-edge-computing-architecture.md +33 -0
- package/references/67-storage-infrastructure-and-storage-systems.md +34 -0
- package/references/68-tcp-quic-and-network-performance.md +27 -0
- package/references/69-task-routing-and-evidence.md +115 -0
- package/scripts/audit_chain.py +36 -0
- package/scripts/compare_reports.py +43 -0
- package/scripts/evaluate.py +475 -0
- package/scripts/evaluation_catalog.py +129 -0
- package/scripts/evaluation_fingerprints.py +20 -0
- package/scripts/evidence_archive.py +79 -0
- package/scripts/evidence_signing.py +98 -0
- package/scripts/evidence_timestamp.py +441 -0
- package/scripts/install.ps1 +12 -3
- package/scripts/install.sh +15 -8
- package/scripts/report_integrity.py +184 -0
- package/scripts/review_consensus.py +77 -0
- package/scripts/review_evidence.py +105 -0
- package/scripts/review_provenance.py +44 -0
- package/scripts/reviewer_calibration.py +215 -0
- package/scripts/rubric_compatibility.py +134 -0
- package/scripts/run_evals.py +130 -0
- package/scripts/run_manifest.py +179 -0
- package/scripts/statistical_analysis.py +308 -0
- package/scripts/tsa_attestation.py +709 -0
- package/scripts/tsa_validation_report.py +627 -0
- package/scripts/validate.py +356 -11
- package/scripts/verify_build_provenance.py +625 -0
- package/scripts/verify_tsa_ocsp.py +962 -0
- package/scripts/verify_tsa_revocation.py +782 -0
- package/scripts/windows_broker_protocol.py +274 -0
- package/scripts/windows_broker_transport.py +141 -0
- package/scripts/windows_broker_win32.py +713 -0
- package/templates/agent-evaluation-plan-template.md +57 -0
- package/templates/agent-security-review-template.md +46 -0
- package/templates/agent-system-design-template.md +74 -0
- package/templates/api-architecture-design-template.md +33 -0
- package/templates/api-security-and-rate-limit-review-template.md +29 -0
- package/templates/architecture-decision-matrix-template.md +48 -0
- package/templates/architecture-review-scorecard-template.md +36 -0
- package/templates/cdc-data-pipeline-template.md +41 -0
- package/templates/cdn-and-edge-strategy-template.md +36 -0
- package/templates/chaos-experiment-template.md +39 -0
- package/templates/cloud-cost-model-template.md +37 -0
- package/templates/database-architecture-review-template.md +33 -0
- package/templates/edge-computing-readiness-template.md +36 -0
- package/templates/event-sourcing-cqrs-template.md +41 -0
- package/templates/event-streaming-design-template.md +47 -0
- package/templates/failure-analysis-template.md +36 -0
- package/templates/identity-and-access-architecture-template.md +29 -0
- package/templates/incident-postmortem-template.md +39 -0
- package/templates/multi-region-disaster-recovery-template.md +43 -0
- package/templates/network-architecture-design-template.md +38 -0
- package/templates/observability-architecture-template.md +52 -0
- package/templates/performance-test-plan-template.md +52 -0
- package/templates/privacy-data-governance-template.md +24 -0
- package/templates/production-readiness-checklist-template.md +52 -0
- package/templates/realtime-system-design-template.md +28 -0
- package/templates/security-threat-model-template.md +26 -0
- package/templates/sharding-distributed-sql-design-template.md +34 -0
- package/templates/storage-architecture-design-template.md +35 -0
- package/templates/supply-chain-security-review-template.md +20 -0
- package/templates/zero-downtime-database-migration-template.md +32 -0
|
@@ -0,0 +1,274 @@
|
|
|
1
|
+
"""Bounded, versioned framing for the Windows process broker IPC.
|
|
2
|
+
|
|
3
|
+
This module is intentionally platform-neutral: importing and testing the wire
|
|
4
|
+
protocol must not load Win32 libraries or create operating-system resources.
|
|
5
|
+
"""
|
|
6
|
+
from __future__ import annotations
|
|
7
|
+
|
|
8
|
+
import json
|
|
9
|
+
import re
|
|
10
|
+
import struct
|
|
11
|
+
import subprocess
|
|
12
|
+
from typing import BinaryIO, Any
|
|
13
|
+
|
|
14
|
+
PROTOCOL_VERSION = 1
|
|
15
|
+
MAX_FRAME_BYTES = 1024 * 1024
|
|
16
|
+
_HEADER = struct.Struct("!I")
|
|
17
|
+
_REQUEST_ID_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$")
|
|
18
|
+
_MESSAGE_TYPES = frozenset({
|
|
19
|
+
"broker_ready",
|
|
20
|
+
"launch",
|
|
21
|
+
"launch_result",
|
|
22
|
+
"handles_ack",
|
|
23
|
+
"cancel",
|
|
24
|
+
"broker_error",
|
|
25
|
+
})
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class ProtocolError(ValueError):
|
|
29
|
+
"""Raised when an IPC frame is malformed or violates protocol limits."""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _reject_constant(value: str) -> None:
|
|
33
|
+
raise ProtocolError(f"non-finite JSON number is not permitted: {value}")
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
|
|
37
|
+
result: dict[str, Any] = {}
|
|
38
|
+
for key, value in pairs:
|
|
39
|
+
if key in result:
|
|
40
|
+
raise ProtocolError(f"duplicate JSON object key: {key}")
|
|
41
|
+
result[key] = value
|
|
42
|
+
return result
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def validate_message(message: Any) -> dict[str, Any]:
|
|
46
|
+
"""Validate the stable envelope while leaving payload schemas to handlers."""
|
|
47
|
+
if not isinstance(message, dict):
|
|
48
|
+
raise ProtocolError("message must be a JSON object")
|
|
49
|
+
expected = {"version", "type", "request_id", "payload"}
|
|
50
|
+
if set(message) != expected:
|
|
51
|
+
missing = sorted(expected - set(message))
|
|
52
|
+
extra = sorted(set(message) - expected)
|
|
53
|
+
raise ProtocolError(f"invalid message fields (missing={missing}, extra={extra})")
|
|
54
|
+
if type(message["version"]) is not int or message["version"] != PROTOCOL_VERSION:
|
|
55
|
+
raise ProtocolError(f"unsupported protocol version: {message['version']!r}")
|
|
56
|
+
message_type = message["type"]
|
|
57
|
+
if not isinstance(message_type, str) or message_type not in _MESSAGE_TYPES:
|
|
58
|
+
raise ProtocolError(f"unsupported message type: {message_type!r}")
|
|
59
|
+
request_id = message["request_id"]
|
|
60
|
+
if not isinstance(request_id, str) or not _REQUEST_ID_RE.fullmatch(request_id):
|
|
61
|
+
raise ProtocolError("request_id must be 1-128 safe ASCII characters")
|
|
62
|
+
if not isinstance(message["payload"], dict):
|
|
63
|
+
raise ProtocolError("payload must be a JSON object")
|
|
64
|
+
_validate_payload(message_type, message["payload"])
|
|
65
|
+
return message
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
def _require_fields(payload: dict[str, Any], expected: set[str], label: str) -> None:
|
|
69
|
+
if set(payload) != expected:
|
|
70
|
+
missing = sorted(expected - set(payload))
|
|
71
|
+
extra = sorted(set(payload) - expected)
|
|
72
|
+
raise ProtocolError(f"{label} payload fields invalid (missing={missing}, extra={extra})")
|
|
73
|
+
|
|
74
|
+
|
|
75
|
+
def _require_text(value: Any, label: str, *, allow_empty: bool = False, maximum: int = 32767) -> None:
|
|
76
|
+
if not isinstance(value, str) or (not allow_empty and not value) or len(value) > maximum or "\x00" in value:
|
|
77
|
+
raise ProtocolError(f"{label} must be a NUL-free string of at most {maximum} characters")
|
|
78
|
+
|
|
79
|
+
|
|
80
|
+
def _require_handle(value: Any, label: str) -> None:
|
|
81
|
+
if type(value) is not int or value <= 0 or value > 0xFFFFFFFFFFFFFFFF:
|
|
82
|
+
raise ProtocolError(f"{label} must be a positive unsigned 64-bit handle value")
|
|
83
|
+
|
|
84
|
+
|
|
85
|
+
def _validate_payload(message_type: str, payload: dict[str, Any]) -> None:
|
|
86
|
+
if message_type == "broker_ready":
|
|
87
|
+
_require_fields(payload, {"broker_pid"}, message_type)
|
|
88
|
+
if type(payload["broker_pid"]) is not int or payload["broker_pid"] <= 0:
|
|
89
|
+
raise ProtocolError("broker_pid must be a positive integer")
|
|
90
|
+
elif message_type == "launch":
|
|
91
|
+
_require_fields(payload, {"application", "argv", "cwd", "environment", "stdin_handle", "stdout_handle", "stderr_handle"}, message_type)
|
|
92
|
+
_require_text(payload["application"], "application")
|
|
93
|
+
argv = payload["argv"]
|
|
94
|
+
if not isinstance(argv, list) or not argv or len(argv) > 4096:
|
|
95
|
+
raise ProtocolError("argv must be a non-empty list of at most 4096 strings")
|
|
96
|
+
for index, argument in enumerate(argv):
|
|
97
|
+
_require_text(argument, f"argv[{index}]", allow_empty=True)
|
|
98
|
+
cwd = payload["cwd"]
|
|
99
|
+
if cwd is not None:
|
|
100
|
+
_require_text(cwd, "cwd")
|
|
101
|
+
environment = payload["environment"]
|
|
102
|
+
if not isinstance(environment, dict) or len(environment) > 32767:
|
|
103
|
+
raise ProtocolError("environment must be an object with at most 32767 entries")
|
|
104
|
+
environment_chars = 1
|
|
105
|
+
for key, value in environment.items():
|
|
106
|
+
_require_text(key, "environment key")
|
|
107
|
+
if "=" in key and re.fullmatch(r"=[A-Za-z]:", key) is None:
|
|
108
|
+
raise ProtocolError("environment keys may contain '=' only for drive-current-directory entries")
|
|
109
|
+
_require_text(value, f"environment[{key!r}]", allow_empty=True)
|
|
110
|
+
environment_chars += len(key) + len(value) + 2
|
|
111
|
+
if environment_chars > 32767:
|
|
112
|
+
raise ProtocolError("environment block exceeds the Windows 32767-character limit")
|
|
113
|
+
if len(subprocess.list2cmdline(argv)) + 1 > 32767:
|
|
114
|
+
raise ProtocolError("argv exceeds the Windows command-line length limit")
|
|
115
|
+
for name in ("stdin_handle", "stdout_handle", "stderr_handle"):
|
|
116
|
+
_require_handle(payload[name], name)
|
|
117
|
+
elif message_type == "launch_result":
|
|
118
|
+
status = payload.get("status")
|
|
119
|
+
if status == "created":
|
|
120
|
+
_require_fields(payload, {"status", "pid", "process_handle", "job_handle"}, message_type)
|
|
121
|
+
if type(payload["pid"]) is not int or payload["pid"] <= 0:
|
|
122
|
+
raise ProtocolError("pid must be a positive integer")
|
|
123
|
+
_require_handle(payload["process_handle"], "process_handle")
|
|
124
|
+
_require_handle(payload["job_handle"], "job_handle")
|
|
125
|
+
elif status == "failed":
|
|
126
|
+
_require_fields(payload, {"status", "error_code", "message"}, message_type)
|
|
127
|
+
if type(payload["error_code"]) is not int or payload["error_code"] < 0:
|
|
128
|
+
raise ProtocolError("error_code must be a non-negative integer")
|
|
129
|
+
_require_text(payload["message"], "message", allow_empty=True, maximum=4096)
|
|
130
|
+
else:
|
|
131
|
+
raise ProtocolError("launch_result status must be 'created' or 'failed'")
|
|
132
|
+
elif message_type == "handles_ack":
|
|
133
|
+
_require_fields(payload, {"accepted"}, message_type)
|
|
134
|
+
if type(payload["accepted"]) is not bool or not payload["accepted"]:
|
|
135
|
+
raise ProtocolError("handles_ack accepted must be true")
|
|
136
|
+
elif message_type == "cancel":
|
|
137
|
+
_require_fields(payload, set(), message_type)
|
|
138
|
+
elif message_type == "broker_error":
|
|
139
|
+
_require_fields(payload, {"code", "message"}, message_type)
|
|
140
|
+
_require_text(payload["code"], "code", maximum=128)
|
|
141
|
+
_require_text(payload["message"], "message", allow_empty=True, maximum=4096)
|
|
142
|
+
|
|
143
|
+
|
|
144
|
+
class BrokerProtocolState:
|
|
145
|
+
"""Enforce one launch request's directional message ordering."""
|
|
146
|
+
|
|
147
|
+
_TERMINAL = frozenset({"complete", "failed", "cancelled"})
|
|
148
|
+
|
|
149
|
+
def __init__(self, role: str, request_id: str):
|
|
150
|
+
if role not in {"host", "broker"}:
|
|
151
|
+
raise ValueError("role must be 'host' or 'broker'")
|
|
152
|
+
if not isinstance(request_id, str) or not _REQUEST_ID_RE.fullmatch(request_id):
|
|
153
|
+
raise ValueError("request_id must be 1-128 safe ASCII characters")
|
|
154
|
+
self.role = role
|
|
155
|
+
self.request_id = request_id
|
|
156
|
+
self.state = "start"
|
|
157
|
+
|
|
158
|
+
def advance(self, direction: str, message: Any) -> str:
|
|
159
|
+
"""Apply one sent/received message and return the new state."""
|
|
160
|
+
validated = validate_message(message)
|
|
161
|
+
if direction not in {"send", "receive"}:
|
|
162
|
+
raise ValueError("direction must be 'send' or 'receive'")
|
|
163
|
+
if validated["request_id"] != self.request_id:
|
|
164
|
+
raise ProtocolError("message request_id does not match active request")
|
|
165
|
+
kind = validated["type"]
|
|
166
|
+
payload = validated["payload"]
|
|
167
|
+
if self.state in self._TERMINAL:
|
|
168
|
+
raise ProtocolError(f"message {kind!r} is invalid after terminal state {self.state!r}")
|
|
169
|
+
if kind == "broker_error" and (
|
|
170
|
+
(self.role == "host" and direction == "receive")
|
|
171
|
+
or (self.role == "broker" and direction == "send")
|
|
172
|
+
):
|
|
173
|
+
self.state = "failed"
|
|
174
|
+
return self.state
|
|
175
|
+
|
|
176
|
+
event = (self.state, direction, kind)
|
|
177
|
+
if self.role == "host":
|
|
178
|
+
transitions = {
|
|
179
|
+
("start", "receive", "broker_ready"): "ready",
|
|
180
|
+
("ready", "send", "launch"): "waiting_result",
|
|
181
|
+
("result_received", "send", "handles_ack"): "complete",
|
|
182
|
+
("result_received", "send", "cancel"): "cancelled",
|
|
183
|
+
("waiting_result", "send", "cancel"): "cancelled",
|
|
184
|
+
}
|
|
185
|
+
if event == ("waiting_result", "receive", "launch_result"):
|
|
186
|
+
next_state = "result_received" if payload["status"] == "created" else "failed"
|
|
187
|
+
else:
|
|
188
|
+
next_state = transitions.get(event)
|
|
189
|
+
else:
|
|
190
|
+
transitions = {
|
|
191
|
+
("start", "send", "broker_ready"): "ready",
|
|
192
|
+
("ready", "receive", "launch"): "launched",
|
|
193
|
+
("ready", "receive", "cancel"): "cancelled",
|
|
194
|
+
("launched", "receive", "cancel"): "cancelled",
|
|
195
|
+
("awaiting_ack", "receive", "handles_ack"): "complete",
|
|
196
|
+
("awaiting_ack", "receive", "cancel"): "cancelled",
|
|
197
|
+
}
|
|
198
|
+
if event == ("launched", "send", "launch_result"):
|
|
199
|
+
next_state = "awaiting_ack" if payload["status"] == "created" else "failed"
|
|
200
|
+
else:
|
|
201
|
+
next_state = transitions.get(event)
|
|
202
|
+
if next_state is None:
|
|
203
|
+
raise ProtocolError(f"unexpected {direction} {kind!r} in state {self.state!r}")
|
|
204
|
+
self.state = next_state
|
|
205
|
+
return self.state
|
|
206
|
+
|
|
207
|
+
|
|
208
|
+
def encode_message(message: Any) -> bytes:
|
|
209
|
+
"""Encode one message as a 4-byte network-order length plus UTF-8 JSON."""
|
|
210
|
+
validated = validate_message(message)
|
|
211
|
+
try:
|
|
212
|
+
body = json.dumps(
|
|
213
|
+
validated,
|
|
214
|
+
ensure_ascii=False,
|
|
215
|
+
allow_nan=False,
|
|
216
|
+
separators=(",", ":"),
|
|
217
|
+
sort_keys=True,
|
|
218
|
+
).encode("utf-8", errors="strict")
|
|
219
|
+
except (TypeError, ValueError, UnicodeError) as exc:
|
|
220
|
+
raise ProtocolError(f"message is not JSON-serializable: {exc}") from exc
|
|
221
|
+
if not body or len(body) > MAX_FRAME_BYTES:
|
|
222
|
+
raise ProtocolError(
|
|
223
|
+
f"encoded frame length {len(body)} exceeds limit {MAX_FRAME_BYTES}"
|
|
224
|
+
)
|
|
225
|
+
return _HEADER.pack(len(body)) + body
|
|
226
|
+
|
|
227
|
+
|
|
228
|
+
def _read_exact(stream: BinaryIO, length: int) -> bytes:
|
|
229
|
+
chunks = bytearray()
|
|
230
|
+
while len(chunks) < length:
|
|
231
|
+
chunk = stream.read(length - len(chunks))
|
|
232
|
+
if not chunk:
|
|
233
|
+
raise ProtocolError(
|
|
234
|
+
f"truncated IPC frame: expected {length} bytes, received {len(chunks)}"
|
|
235
|
+
)
|
|
236
|
+
chunks.extend(chunk)
|
|
237
|
+
return bytes(chunks)
|
|
238
|
+
|
|
239
|
+
|
|
240
|
+
def read_message(stream: BinaryIO) -> dict[str, Any]:
|
|
241
|
+
"""Read exactly one bounded frame from a blocking binary stream."""
|
|
242
|
+
header = _read_exact(stream, _HEADER.size)
|
|
243
|
+
(length,) = _HEADER.unpack(header)
|
|
244
|
+
if length == 0 or length > MAX_FRAME_BYTES:
|
|
245
|
+
raise ProtocolError(
|
|
246
|
+
f"invalid IPC frame length {length}; maximum is {MAX_FRAME_BYTES}"
|
|
247
|
+
)
|
|
248
|
+
body = _read_exact(stream, length)
|
|
249
|
+
try:
|
|
250
|
+
decoded = body.decode("utf-8", errors="strict")
|
|
251
|
+
message = json.loads(
|
|
252
|
+
decoded,
|
|
253
|
+
object_pairs_hook=_unique_object,
|
|
254
|
+
parse_constant=_reject_constant,
|
|
255
|
+
)
|
|
256
|
+
except ProtocolError:
|
|
257
|
+
raise
|
|
258
|
+
except (UnicodeDecodeError, json.JSONDecodeError) as exc:
|
|
259
|
+
raise ProtocolError(f"invalid IPC JSON: {exc}") from exc
|
|
260
|
+
return validate_message(message)
|
|
261
|
+
|
|
262
|
+
|
|
263
|
+
def write_message(stream: BinaryIO, message: Any) -> None:
|
|
264
|
+
"""Write a complete frame, handling streams that perform short writes."""
|
|
265
|
+
frame = encode_message(message)
|
|
266
|
+
offset = 0
|
|
267
|
+
while offset < len(frame):
|
|
268
|
+
written = stream.write(frame[offset:])
|
|
269
|
+
if written is None or written <= 0:
|
|
270
|
+
raise ProtocolError("IPC stream made no progress while writing")
|
|
271
|
+
offset += written
|
|
272
|
+
flush = getattr(stream, "flush", None)
|
|
273
|
+
if flush is not None:
|
|
274
|
+
flush()
|
|
@@ -0,0 +1,141 @@
|
|
|
1
|
+
"""Platform-neutral primitives for the Windows broker named-pipe transport.
|
|
2
|
+
|
|
3
|
+
This module deliberately does not load Win32 APIs. The native adapter must own
|
|
4
|
+
OVERLAPPED/event lifetime and cancel/drain semantics; these helpers provide
|
|
5
|
+
bounded, deterministic byte-stream operations for that adapter.
|
|
6
|
+
"""
|
|
7
|
+
from __future__ import annotations
|
|
8
|
+
|
|
9
|
+
import math
|
|
10
|
+
import re
|
|
11
|
+
import secrets
|
|
12
|
+
import time
|
|
13
|
+
from collections.abc import Callable
|
|
14
|
+
|
|
15
|
+
PIPE_PREFIX = "\\\\.\\pipe\\"
|
|
16
|
+
_PIPE_BASENAME = re.compile(r"^broker-[0-9a-f]{64}$")
|
|
17
|
+
MAX_PIPE_NAME_LENGTH = 256
|
|
18
|
+
|
|
19
|
+
|
|
20
|
+
class PipeTransportError(OSError):
|
|
21
|
+
"""Base class for named-pipe transport failures."""
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
class PipeDeadlineExceeded(PipeTransportError, TimeoutError):
|
|
25
|
+
"""An absolute monotonic I/O deadline expired."""
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
class PipePeerClosed(PipeTransportError, EOFError):
|
|
29
|
+
"""The peer closed the byte stream before the requested bytes arrived."""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
class PipeNoProgress(PipeTransportError):
|
|
33
|
+
"""An I/O callback completed without making forward progress."""
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
class Deadline:
|
|
37
|
+
"""An absolute deadline measured against a monotonic clock."""
|
|
38
|
+
|
|
39
|
+
__slots__ = ("_expires_at", "_clock")
|
|
40
|
+
|
|
41
|
+
def __init__(
|
|
42
|
+
self,
|
|
43
|
+
timeout: float,
|
|
44
|
+
*,
|
|
45
|
+
clock: Callable[[], float] = time.monotonic,
|
|
46
|
+
) -> None:
|
|
47
|
+
if isinstance(timeout, bool) or not isinstance(timeout, (int, float)):
|
|
48
|
+
raise TypeError("timeout must be a finite non-negative number")
|
|
49
|
+
if not math.isfinite(timeout) or timeout < 0:
|
|
50
|
+
raise ValueError("timeout must be a finite non-negative number")
|
|
51
|
+
self._clock = clock
|
|
52
|
+
self._expires_at = clock() + float(timeout)
|
|
53
|
+
|
|
54
|
+
@property
|
|
55
|
+
def remaining(self) -> float:
|
|
56
|
+
"""Return remaining seconds, clamped to zero."""
|
|
57
|
+
return max(0.0, self._expires_at - self._clock())
|
|
58
|
+
|
|
59
|
+
@property
|
|
60
|
+
def expired(self) -> bool:
|
|
61
|
+
return self.remaining <= 0.0
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
def new_pipe_name(token_bytes: Callable[[int], bytes] = secrets.token_bytes) -> str:
|
|
65
|
+
"""Create a per-launch pipe name with 256 bits of cryptographic randomness."""
|
|
66
|
+
token = token_bytes(32)
|
|
67
|
+
if not isinstance(token, bytes) or len(token) != 32:
|
|
68
|
+
raise ValueError("token source must return exactly 32 bytes")
|
|
69
|
+
return PIPE_PREFIX + "broker-" + token.hex()
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def validate_pipe_name(name: str) -> str:
|
|
73
|
+
"""Accept only this transport's canonical local named-pipe namespace."""
|
|
74
|
+
if not isinstance(name, str):
|
|
75
|
+
raise TypeError("pipe name must be a string")
|
|
76
|
+
if len(name) > MAX_PIPE_NAME_LENGTH or not name.startswith(PIPE_PREFIX):
|
|
77
|
+
raise ValueError("pipe name is outside the permitted local namespace")
|
|
78
|
+
basename = name[len(PIPE_PREFIX):]
|
|
79
|
+
if not _PIPE_BASENAME.fullmatch(basename):
|
|
80
|
+
raise ValueError("pipe name must contain a canonical 256-bit broker token")
|
|
81
|
+
return name
|
|
82
|
+
|
|
83
|
+
|
|
84
|
+
def read_exact(
|
|
85
|
+
read_chunk: Callable[[int, float], bytes],
|
|
86
|
+
length: int,
|
|
87
|
+
deadline: Deadline,
|
|
88
|
+
) -> bytes:
|
|
89
|
+
"""Read exactly length bytes; callbacks receive size and remaining timeout."""
|
|
90
|
+
if type(length) is not int or length < 0:
|
|
91
|
+
raise ValueError("length must be a non-negative integer")
|
|
92
|
+
chunks = bytearray()
|
|
93
|
+
while len(chunks) < length:
|
|
94
|
+
remaining = deadline.remaining
|
|
95
|
+
if remaining <= 0.0:
|
|
96
|
+
raise PipeDeadlineExceeded("named-pipe read deadline expired")
|
|
97
|
+
try:
|
|
98
|
+
chunk = read_chunk(length - len(chunks), remaining)
|
|
99
|
+
except TimeoutError as exc:
|
|
100
|
+
raise PipeDeadlineExceeded("named-pipe read deadline expired") from exc
|
|
101
|
+
if deadline.expired:
|
|
102
|
+
raise PipeDeadlineExceeded("named-pipe read deadline expired")
|
|
103
|
+
if not isinstance(chunk, bytes):
|
|
104
|
+
raise TypeError("read callback must return bytes")
|
|
105
|
+
if not chunk:
|
|
106
|
+
raise PipePeerClosed(
|
|
107
|
+
f"peer closed after {len(chunks)} of {length} requested bytes"
|
|
108
|
+
)
|
|
109
|
+
if len(chunk) > length - len(chunks):
|
|
110
|
+
raise PipeTransportError("read callback returned more bytes than requested")
|
|
111
|
+
chunks.extend(chunk)
|
|
112
|
+
return bytes(chunks)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def write_all(
|
|
116
|
+
write_chunk: Callable[[memoryview, float], int],
|
|
117
|
+
data: bytes,
|
|
118
|
+
deadline: Deadline,
|
|
119
|
+
) -> None:
|
|
120
|
+
"""Write all bytes, correctly handling short writes under one deadline."""
|
|
121
|
+
if not isinstance(data, bytes):
|
|
122
|
+
raise TypeError("data must be bytes")
|
|
123
|
+
view = memoryview(data)
|
|
124
|
+
offset = 0
|
|
125
|
+
while offset < len(view):
|
|
126
|
+
remaining = deadline.remaining
|
|
127
|
+
if remaining <= 0.0:
|
|
128
|
+
raise PipeDeadlineExceeded("named-pipe write deadline expired")
|
|
129
|
+
try:
|
|
130
|
+
written = write_chunk(view[offset:], remaining)
|
|
131
|
+
except TimeoutError as exc:
|
|
132
|
+
raise PipeDeadlineExceeded("named-pipe write deadline expired") from exc
|
|
133
|
+
if deadline.expired:
|
|
134
|
+
raise PipeDeadlineExceeded("named-pipe write deadline expired")
|
|
135
|
+
if type(written) is not int:
|
|
136
|
+
raise TypeError("write callback must return an integer byte count")
|
|
137
|
+
if written <= 0:
|
|
138
|
+
raise PipeNoProgress("named-pipe write made no progress")
|
|
139
|
+
if written > len(view) - offset:
|
|
140
|
+
raise PipeTransportError("write callback reported more bytes than supplied")
|
|
141
|
+
offset += written
|