system-design-primer-skill 2.3.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.
Files changed (66) hide show
  1. package/README.md +15 -7
  2. package/SKILL.md +22 -2
  3. package/VERSION +1 -1
  4. package/evals/README.md +1022 -0
  5. package/evals/system-design-cases.json +414 -0
  6. package/package.json +3 -2
  7. package/references/03-data-and-storage.md +8 -2
  8. package/references/04-caching.md +3 -3
  9. package/references/05-async-and-messaging.md +4 -0
  10. package/references/06-distributed-systems.md +2 -2
  11. package/references/07-reliability-and-resilience.md +7 -3
  12. package/references/08-api-security-observability.md +4 -0
  13. package/references/15-failure-analysis.md +4 -0
  14. package/references/19-agent-security-and-permissions.md +22 -6
  15. package/references/20-agent-state-and-memory.md +4 -0
  16. package/references/22-kubernetes-and-container-platforms.md +1 -1
  17. package/references/24-multi-region-and-disaster-recovery.md +6 -2
  18. package/references/27-production-observability-and-slo.md +4 -0
  19. package/references/28-event-streaming-and-kafka-pulsar.md +6 -0
  20. package/references/32-workflow-orchestration-and-temporal.md +4 -0
  21. package/references/34-postgresql-internals-and-performance.md +2 -0
  22. package/references/35-mysql-innodb-and-performance.md +2 -0
  23. package/references/36-sharding-and-distributed-sql.md +1 -1
  24. package/references/37-consensus-and-distributed-transactions.md +7 -3
  25. package/references/40-zero-downtime-database-migrations.md +3 -3
  26. package/references/48-oauth-oidc-and-passkeys.md +3 -3
  27. package/references/49-iam-rbac-abac-rebac.md +7 -3
  28. package/references/51-secrets-kms-pki-and-key-management.md +4 -0
  29. package/references/52-supply-chain-security-sbom-slsa.md +62 -0
  30. package/references/54-privacy-engineering-and-data-governance.md +4 -0
  31. package/references/55-opentelemetry-and-instrumentation.md +4 -0
  32. package/references/56-distributed-tracing-and-context-propagation.md +4 -0
  33. package/references/59-capacity-planning-and-performance-modeling.md +8 -4
  34. package/references/60-chaos-engineering-and-resilience-experiments.md +4 -0
  35. package/references/61-incident-management-and-postmortems.md +4 -0
  36. package/references/67-storage-infrastructure-and-storage-systems.md +4 -0
  37. package/references/68-tcp-quic-and-network-performance.md +1 -1
  38. package/references/69-task-routing-and-evidence.md +75 -18
  39. package/scripts/audit_chain.py +36 -0
  40. package/scripts/compare_reports.py +43 -0
  41. package/scripts/evaluate.py +475 -0
  42. package/scripts/evaluation_catalog.py +129 -0
  43. package/scripts/evaluation_fingerprints.py +20 -0
  44. package/scripts/evidence_archive.py +79 -0
  45. package/scripts/evidence_signing.py +98 -0
  46. package/scripts/evidence_timestamp.py +441 -0
  47. package/scripts/install.ps1 +2 -2
  48. package/scripts/install.sh +2 -2
  49. package/scripts/report_integrity.py +184 -0
  50. package/scripts/review_consensus.py +77 -0
  51. package/scripts/review_evidence.py +105 -0
  52. package/scripts/review_provenance.py +44 -0
  53. package/scripts/reviewer_calibration.py +215 -0
  54. package/scripts/rubric_compatibility.py +134 -0
  55. package/scripts/run_evals.py +130 -0
  56. package/scripts/run_manifest.py +179 -0
  57. package/scripts/statistical_analysis.py +308 -0
  58. package/scripts/tsa_attestation.py +709 -0
  59. package/scripts/tsa_validation_report.py +627 -0
  60. package/scripts/validate.py +233 -21
  61. package/scripts/verify_build_provenance.py +625 -0
  62. package/scripts/verify_tsa_ocsp.py +962 -0
  63. package/scripts/verify_tsa_revocation.py +782 -0
  64. package/scripts/windows_broker_protocol.py +274 -0
  65. package/scripts/windows_broker_transport.py +141 -0
  66. package/scripts/windows_broker_win32.py +713 -0
@@ -0,0 +1,713 @@
1
+ """Lazy ctypes bindings and guarded overlapped-operation lifetimes.
2
+
3
+ Importing this module is safe on non-Windows hosts. Native DLL loading is
4
+ explicit; the lifecycle object is callback-driven so its state machine can be
5
+ tested without pretending that mocked tests exercise the Windows kernel.
6
+ """
7
+ from __future__ import annotations
8
+
9
+ import ctypes
10
+ import os
11
+ import threading
12
+ from dataclasses import dataclass
13
+ from typing import Any, Callable
14
+
15
+
16
+ # Fixed-width Win32 scalar types (POSIX c_ulong is commonly 64-bit).
17
+ DWORD = ctypes.c_uint32
18
+ BOOL = ctypes.c_int32
19
+ HANDLE = ctypes.c_void_p
20
+ ULONG_PTR = ctypes.c_size_t
21
+ LPVOID = ctypes.c_void_p
22
+ LPCWSTR = ctypes.c_wchar_p
23
+
24
+ ERROR_IO_PENDING = 997
25
+ ERROR_IO_INCOMPLETE = 996
26
+ ERROR_NOT_FOUND = 1168
27
+ ERROR_OPERATION_ABORTED = 995
28
+ ERROR_INVALID_HANDLE = 6
29
+ ERROR_INVALID_PARAMETER = 87
30
+ ERROR_PIPE_CONNECTED = 535
31
+ MAX_DWORD = 0xFFFFFFFF
32
+ WAIT_OBJECT_0 = 0
33
+ WAIT_TIMEOUT = 258
34
+ WAIT_FAILED = 0xFFFFFFFF
35
+ INFINITE = 0xFFFFFFFF
36
+
37
+
38
+ class _OffsetUnion(ctypes.Union):
39
+ _fields_ = [("_offset", DWORD * 2), ("_pointer", LPVOID)]
40
+
41
+
42
+ class OVERLAPPED(ctypes.Structure):
43
+ """Native OVERLAPPED layout with pointer-sized internal fields."""
44
+
45
+ _anonymous_ = ("_offset_union",)
46
+ _fields_ = [
47
+ ("Internal", ULONG_PTR),
48
+ ("InternalHigh", ULONG_PTR),
49
+ ("_offset_union", _OffsetUnion),
50
+ ("hEvent", HANDLE),
51
+ ]
52
+
53
+
54
+ class Win32ApiUnavailable(RuntimeError):
55
+ """Raised when native Windows APIs cannot be loaded."""
56
+
57
+
58
+ class OverlappedLifecycleError(RuntimeError):
59
+ """Raised when an operation is used outside its valid lifecycle."""
60
+
61
+
62
+ class OverlappedStillPending(OverlappedLifecycleError):
63
+ """Raised when a drain attempt has not established completion."""
64
+
65
+
66
+ @dataclass(frozen=True)
67
+ class OverlappedResult:
68
+ succeeded: bool
69
+ bytes_transferred: int
70
+ error_code: int
71
+ cancel_error: int | None
72
+
73
+
74
+ @dataclass(frozen=True)
75
+ class Kernel32Bindings:
76
+ """Typed function references from kernel32.dll."""
77
+
78
+ library: Any
79
+ CreateEventW: Any
80
+ CloseHandle: Any
81
+ WaitForSingleObject: Any
82
+ CancelIoEx: Any
83
+ GetOverlappedResult: Any
84
+ GetOverlappedResultEx: Any
85
+ ReadFile: Any = None
86
+ WriteFile: Any = None
87
+ ConnectNamedPipe: Any = None
88
+ SetEvent: Any = None
89
+ DisconnectNamedPipe: Any = None
90
+
91
+
92
+ def _set_signature(function: Any, argtypes: list[Any], restype: Any) -> Any:
93
+ function.argtypes = argtypes
94
+ function.restype = restype
95
+ return function
96
+
97
+
98
+ def load_kernel32(*, loader: Any = None) -> Kernel32Bindings:
99
+ """Load and type-check required APIs; callable injection is for unit tests."""
100
+ if os.name != "nt":
101
+ raise Win32ApiUnavailable("the Windows broker transport requires Windows")
102
+ load_library = loader or ctypes.WinDLL
103
+ try:
104
+ library = load_library("kernel32", use_last_error=True)
105
+ create_event = _set_signature(
106
+ library.CreateEventW, [LPVOID, BOOL, BOOL, LPCWSTR], HANDLE
107
+ )
108
+ close_handle = _set_signature(library.CloseHandle, [HANDLE], BOOL)
109
+ wait = _set_signature(library.WaitForSingleObject, [HANDLE, DWORD], DWORD)
110
+ cancel = _set_signature(
111
+ library.CancelIoEx, [HANDLE, ctypes.POINTER(OVERLAPPED)], BOOL
112
+ )
113
+ get_result = _set_signature(
114
+ library.GetOverlappedResult,
115
+ [HANDLE, ctypes.POINTER(OVERLAPPED), ctypes.POINTER(DWORD), BOOL],
116
+ BOOL,
117
+ )
118
+ read_file = _set_signature(library.ReadFile, [HANDLE, LPVOID, DWORD, ctypes.POINTER(DWORD), ctypes.POINTER(OVERLAPPED)], BOOL)
119
+ write_file = _set_signature(library.WriteFile, [HANDLE, LPVOID, DWORD, ctypes.POINTER(DWORD), ctypes.POINTER(OVERLAPPED)], BOOL)
120
+ connect_named_pipe = _set_signature(library.ConnectNamedPipe, [HANDLE, ctypes.POINTER(OVERLAPPED)], BOOL)
121
+ set_event = _set_signature(library.SetEvent, [HANDLE], BOOL)
122
+ disconnect_named_pipe = _set_signature(library.DisconnectNamedPipe, [HANDLE], BOOL)
123
+ get_result_ex = _set_signature(
124
+ library.GetOverlappedResultEx,
125
+ [
126
+ HANDLE,
127
+ ctypes.POINTER(OVERLAPPED),
128
+ ctypes.POINTER(DWORD),
129
+ DWORD,
130
+ BOOL,
131
+ ],
132
+ BOOL,
133
+ )
134
+ except (AttributeError, OSError) as exc:
135
+ raise Win32ApiUnavailable(
136
+ "kernel32 is missing a required overlapped-I/O API"
137
+ ) from exc
138
+ return Kernel32Bindings(
139
+ library, create_event, close_handle, wait, cancel, get_result, get_result_ex, read_file, write_file, connect_named_pipe, set_event, disconnect_named_pipe
140
+ )
141
+
142
+
143
+ def last_error() -> int:
144
+ """Return the calling thread's Win32 last-error value."""
145
+ getter = getattr(ctypes, "get_last_error", None)
146
+ if getter is None:
147
+ raise Win32ApiUnavailable("Win32 last-error state is unavailable")
148
+ return int(getter())
149
+
150
+
151
+ def create_manual_reset_event(
152
+ bindings: Kernel32Bindings, *, get_last_error: Callable[[], int] = last_error
153
+ ) -> tuple[Any, int | None]:
154
+ """Create a non-inheritable, initially nonsignaled manual-reset event."""
155
+ handle = bindings.CreateEventW(None, BOOL(1), BOOL(0), None)
156
+ if not handle:
157
+ return None, int(get_last_error())
158
+ return handle, None
159
+
160
+
161
+ def close_kernel_handle(
162
+ bindings: Kernel32Bindings, handle: Any,
163
+ *, get_last_error: Callable[[], int] = last_error,
164
+ ) -> tuple[bool, int | None]:
165
+ """Close a kernel handle and capture GetLastError immediately on failure."""
166
+ succeeded = bool(bindings.CloseHandle(handle))
167
+ return (True, None) if succeeded else (False, int(get_last_error()))
168
+
169
+
170
+ def cancel_exact_io(
171
+ bindings: Kernel32Bindings, file_handle: Any, overlapped: OVERLAPPED,
172
+ *, get_last_error: Callable[[], int] = last_error,
173
+ ) -> tuple[bool, int | None]:
174
+ """Request cancellation for exactly one OVERLAPPED operation."""
175
+ succeeded = bool(bindings.CancelIoEx(file_handle, ctypes.byref(overlapped)))
176
+ return (True, None) if succeeded else (False, int(get_last_error()))
177
+
178
+
179
+ def get_overlapped_result_wait(
180
+ bindings: Kernel32Bindings, file_handle: Any, overlapped: OVERLAPPED,
181
+ wait: bool = True, *, get_last_error: Callable[[], int] = last_error,
182
+ ) -> tuple[bool, int, int | None]:
183
+ """Read completion status; optionally block until the I/O is terminal."""
184
+ transferred = DWORD(0)
185
+ succeeded = bool(bindings.GetOverlappedResult(
186
+ file_handle, ctypes.byref(overlapped), ctypes.byref(transferred),
187
+ BOOL(1 if wait else 0),
188
+ ))
189
+ error = None if succeeded else int(get_last_error())
190
+ return succeeded, int(transferred.value), error
191
+
192
+
193
+ def get_overlapped_result_ex_wait(
194
+ bindings: Kernel32Bindings, file_handle: Any, overlapped: OVERLAPPED,
195
+ timeout_ms: int, *, get_last_error: Callable[[], int] = last_error,
196
+ ) -> tuple[bool, int, int | None]:
197
+ """Read completion status with a finite timeout and no alertable wait."""
198
+ if not isinstance(timeout_ms, int) or isinstance(timeout_ms, bool):
199
+ raise TypeError("timeout_ms must be an integer")
200
+ if timeout_ms < 0 or timeout_ms >= INFINITE:
201
+ raise ValueError("timeout_ms must be a finite unsigned Win32 timeout")
202
+ transferred = DWORD(0)
203
+ succeeded = bool(bindings.GetOverlappedResultEx(
204
+ file_handle, ctypes.byref(overlapped), ctypes.byref(transferred),
205
+ DWORD(timeout_ms), BOOL(0),
206
+ ))
207
+ error = None if succeeded else int(get_last_error())
208
+ return succeeded, int(transferred.value), error
209
+
210
+
211
+ class NamedPipeConnection:
212
+ """Track server-side connection state independently from one I/O operation."""
213
+
214
+ CONNECTED = "connected"
215
+ CONNECTING = "connecting"
216
+ DISCONNECTED = "disconnected"
217
+ DISCONNECTING = "disconnecting"
218
+ CLOSING = "closing"
219
+ CLOSED = "closed"
220
+
221
+ def __init__(self, file_handle: Any) -> None:
222
+ if not file_handle:
223
+ raise ValueError("a live named-pipe handle is required")
224
+ self.file_handle = file_handle
225
+ self._state = self.CONNECTED
226
+ self._lock = threading.RLock()
227
+ self._operations: set[Any] = set()
228
+ self._connect_operation: Any | None = None
229
+
230
+ @property
231
+ def state(self) -> str:
232
+ with self._lock:
233
+ return self._state
234
+
235
+ def register_operation(self, operation: "OverlappedOperation") -> None:
236
+ """Register every I/O operation issued against this pipe instance."""
237
+ # Lock order is connection -> operation throughout this class.
238
+ # Keep the state check and registry insertion atomic with respect to
239
+ # operation.close(), which takes only the operation lock.
240
+ with self._lock, operation._lock:
241
+ if self._state != self.CONNECTED:
242
+ raise OverlappedLifecycleError(
243
+ "cannot register I/O while pipe is not connected"
244
+ )
245
+ if self._connect_operation is not None:
246
+ raise OverlappedLifecycleError(
247
+ "connect operation resources must be closed and unregistered before I/O"
248
+ )
249
+ if operation.file_handle != self.file_handle:
250
+ raise OverlappedLifecycleError(
251
+ "operation handle does not belong to this pipe connection"
252
+ )
253
+ if operation._state == operation.CLOSED:
254
+ raise OverlappedLifecycleError(
255
+ "cannot register a closed I/O operation"
256
+ )
257
+ self._operations.add(operation)
258
+
259
+ def start_operation(
260
+ self,
261
+ bindings: "Kernel32Bindings",
262
+ operation: "OverlappedOperation",
263
+ *,
264
+ buffer: Any,
265
+ length: int,
266
+ write: bool = False,
267
+ get_last_error: Callable[[], int] = last_error,
268
+ ) -> tuple[str, int, int | None]:
269
+ """Submit registered I/O while excluding concurrent disconnect/reuse.
270
+
271
+ The connection lock remains held through the native ReadFile/WriteFile
272
+ submission. This makes registration, submission, and disconnect one
273
+ serialized lifecycle; callers must not submit registered operations
274
+ through the low-level _start_overlapped_io helper directly.
275
+ """
276
+ with self._lock:
277
+ if self._state != self.CONNECTED:
278
+ raise OverlappedLifecycleError(
279
+ "cannot submit I/O while pipe is not connected"
280
+ )
281
+ if self._connect_operation is not None:
282
+ raise OverlappedLifecycleError(
283
+ "connect operation resources must be closed and unregistered before I/O"
284
+ )
285
+ if operation not in self._operations:
286
+ raise OverlappedLifecycleError(
287
+ "operation must be registered before I/O submission"
288
+ )
289
+ if operation.file_handle != self.file_handle:
290
+ raise OverlappedLifecycleError(
291
+ "operation handle does not belong to this pipe connection"
292
+ )
293
+ if operation.state != operation.CREATED:
294
+ raise OverlappedLifecycleError(
295
+ f"cannot submit operation in state {operation.state}"
296
+ )
297
+ return _start_overlapped_io(
298
+ bindings,
299
+ operation,
300
+ buffer=buffer,
301
+ length=length,
302
+ write=write,
303
+ get_last_error=get_last_error,
304
+ )
305
+
306
+ def unregister_operation(self, operation: "OverlappedOperation") -> None:
307
+ """Forget an operation only after its OVERLAPPED resources are closed."""
308
+ with self._lock:
309
+ if operation not in self._operations:
310
+ raise OverlappedLifecycleError("operation is not registered")
311
+ if operation is self._connect_operation and self._state == self.CONNECTING:
312
+ raise OverlappedLifecycleError(
313
+ "connect result must be committed before unregistering"
314
+ )
315
+ if operation.state != operation.CLOSED:
316
+ raise OverlappedLifecycleError(
317
+ "operation resources must be closed before unregistering"
318
+ )
319
+ self._operations.remove(operation)
320
+ if operation is self._connect_operation:
321
+ self._connect_operation = None
322
+
323
+ def start_connect(
324
+ self,
325
+ bindings: "Kernel32Bindings",
326
+ operation: "OverlappedOperation",
327
+ *,
328
+ get_last_error: Callable[[], int] = last_error,
329
+ ) -> tuple[str, int | None]:
330
+ """Start a new overlapped connection as one serialized lifecycle step.
331
+
332
+ The connect operation is registered before the native call and remains
333
+ registered until its event/buffer/OVERLAPPED resources are closed.
334
+ A pending connect must be finalized with complete_connect after its
335
+ operation reaches COMPLETED.
336
+ """
337
+ with self._lock, operation._lock:
338
+ if self._state != self.DISCONNECTED:
339
+ raise OverlappedLifecycleError(
340
+ f"cannot start pipe connect in state {self._state}"
341
+ )
342
+ if self._operations:
343
+ raise OverlappedLifecycleError(
344
+ "cannot connect while previous operation resources remain registered"
345
+ )
346
+ if operation.file_handle != self.file_handle:
347
+ raise OverlappedLifecycleError(
348
+ "connect operation handle does not belong to this pipe"
349
+ )
350
+ if operation.state != operation.CREATED:
351
+ raise OverlappedLifecycleError(
352
+ f"cannot start connect in operation state {operation.state}"
353
+ )
354
+ self._operations.add(operation)
355
+ self._connect_operation = operation
356
+ self._state = self.CONNECTING
357
+ try:
358
+ result, error = _start_overlapped_connect(
359
+ bindings, operation, get_last_error=get_last_error
360
+ )
361
+ except BaseException:
362
+ # Validation failures before STARTING cannot have reached the
363
+ # kernel, so roll back registration and permit a safe retry.
364
+ # Once submission starts, retain both state and resources until
365
+ # the uncertain kernel operation has been drained.
366
+ if operation.state == operation.CREATED:
367
+ self._operations.discard(operation)
368
+ self._connect_operation = None
369
+ self._state = self.DISCONNECTED
370
+ raise
371
+ if result == "connected":
372
+ self._state = self.CONNECTED
373
+ elif result == "failed":
374
+ self._state = self.DISCONNECTED
375
+ return result, error
376
+
377
+ def complete_connect(
378
+ self, operation: "OverlappedOperation", *, connected: bool
379
+ ) -> None:
380
+ """Commit a pending ConnectNamedPipe result after I/O completion."""
381
+ if type(connected) is not bool:
382
+ raise TypeError("connected must be a bool")
383
+ with self._lock:
384
+ if self._state != self.CONNECTING:
385
+ raise OverlappedLifecycleError(
386
+ f"cannot complete pipe connect in state {self._state}"
387
+ )
388
+ if operation is not self._connect_operation:
389
+ raise OverlappedLifecycleError(
390
+ "operation is not the active ConnectNamedPipe operation"
391
+ )
392
+ if operation not in self._operations:
393
+ raise OverlappedLifecycleError(
394
+ "connect operation is not registered with this pipe"
395
+ )
396
+ # close() is allowed after terminal completion and clears the
397
+ # operation's native handle reference. Preserve the connection-level
398
+ # registration until this result is committed, so callers can still
399
+ # recover safely if they closed the event before committing state.
400
+ if operation.state not in (operation.COMPLETED, operation.CLOSED):
401
+ raise OverlappedLifecycleError(
402
+ "connect operation must be completed before committing its result"
403
+ )
404
+ if operation.state != operation.CLOSED and operation.file_handle != self.file_handle:
405
+ raise OverlappedLifecycleError(
406
+ "connect operation handle does not belong to this pipe"
407
+ )
408
+ self._state = self.CONNECTED if connected else self.DISCONNECTED
409
+
410
+ def mark_connected(self) -> None:
411
+ """Reject state-only reconnects; use start_connect/complete_connect."""
412
+ raise OverlappedLifecycleError(
413
+ "connection state must be established by the ConnectNamedPipe lifecycle"
414
+ )
415
+
416
+
417
+ def disconnect_named_pipe(
418
+ bindings: Kernel32Bindings,
419
+ connection: NamedPipeConnection,
420
+ operation: "OverlappedOperation",
421
+ *,
422
+ get_last_error: Callable[[], int] = last_error,
423
+ ) -> tuple[bool, int | None]:
424
+ """Disconnect once, only after the supplied pipe I/O has completed.
425
+
426
+ Every operation issued against the pipe must first be registered with
427
+ its NamedPipeConnection. All registered operations must be terminal
428
+ (not pending) before disconnect. The registry remains until each operation
429
+ closes its event/buffer/OVERLAPPED resources and is explicitly unregistered.
430
+ """
431
+ with connection._lock:
432
+ if connection._state not in (connection.CONNECTED, connection.DISCONNECTING):
433
+ raise OverlappedLifecycleError(
434
+ f"cannot disconnect pipe in state {connection._state}"
435
+ )
436
+ if operation.state == operation.PENDING:
437
+ raise OverlappedLifecycleError(
438
+ "cannot disconnect a pipe while overlapped I/O is pending"
439
+ )
440
+ if operation.state not in (operation.COMPLETED, operation.CLOSED):
441
+ raise OverlappedLifecycleError(
442
+ "disconnect requires a completed operation"
443
+ )
444
+ # A closed operation clears its native handle reference, but its exact
445
+ # registered identity still proves which pipe lifecycle completed.
446
+ if operation.state != operation.CLOSED and operation.file_handle != connection.file_handle:
447
+ raise OverlappedLifecycleError(
448
+ "operation handle does not belong to this pipe connection"
449
+ )
450
+ if operation not in connection._operations:
451
+ raise OverlappedLifecycleError(
452
+ "operation must be registered with its pipe connection"
453
+ )
454
+ unfinished = [
455
+ item for item in connection._operations
456
+ if item.state not in (item.COMPLETED, item.CLOSED)
457
+ ]
458
+ if unfinished:
459
+ raise OverlappedLifecycleError(
460
+ "cannot disconnect while registered pipe I/O is not completed"
461
+ )
462
+ # Failure does not establish whether the instance remains connected.
463
+ # Block I/O and reconnect until a retry confirms disconnection.
464
+ connection._state = connection.DISCONNECTING
465
+ succeeded = bool(bindings.DisconnectNamedPipe(connection.file_handle))
466
+ if not succeeded:
467
+ return False, int(get_last_error())
468
+ connection._state = connection.DISCONNECTED
469
+ return True, None
470
+
471
+
472
+ def close_named_pipe(
473
+ bindings: Kernel32Bindings,
474
+ connection: NamedPipeConnection,
475
+ *,
476
+ get_last_error: Callable[[], int] = last_error,
477
+ ) -> tuple[bool, int | None]:
478
+ """Close the server pipe handle after disconnect and operation cleanup."""
479
+ with connection._lock:
480
+ if connection._state not in (connection.DISCONNECTED, connection.DISCONNECTING, connection.CLOSING):
481
+ raise OverlappedLifecycleError(
482
+ f"cannot close pipe handle in state {connection._state}"
483
+ )
484
+ if connection._operations:
485
+ raise OverlappedLifecycleError(
486
+ "cannot close pipe handle while registered operation resources remain"
487
+ )
488
+ # A Python/API exception leaves the close outcome uncertain. Keep the
489
+ # handle for a retry, but block reconnect until that retry resolves it.
490
+ connection._state = connection.CLOSING
491
+ succeeded = bool(bindings.CloseHandle(connection.file_handle))
492
+ if not succeeded:
493
+ # A failed CloseHandle does not establish that the numeric handle
494
+ # is still valid. Keep CLOSING so it can only be retried/abandoned,
495
+ # never reused for a new connection.
496
+ return False, int(get_last_error())
497
+ connection.file_handle = None
498
+ connection._state = connection.CLOSED
499
+ return True, None
500
+
501
+
502
+ def _start_overlapped_connect(bindings: Kernel32Bindings, operation: "OverlappedOperation", *, get_last_error: Callable[[], int] = last_error) -> tuple[str, int | None]:
503
+ """Low-level ConnectNamedPipe primitive; prefer NamedPipeConnection.start_connect.
504
+
505
+ This helper owns only the operation state transition. It cannot serialize
506
+ against pipe disconnect/reuse and must not be used as a connection API.
507
+ """
508
+ if operation.state != operation.CREATED:
509
+ raise OverlappedLifecycleError(f"cannot start connect in state {operation.state}")
510
+ if not operation.event_handle:
511
+ raise ValueError("overlapped connect requires an event handle")
512
+ operation.mark_starting()
513
+ operation.overlapped.hEvent = operation.event_handle
514
+ try:
515
+ succeeded = bool(bindings.ConnectNamedPipe(operation.file_handle, ctypes.byref(operation.overlapped)))
516
+ if succeeded:
517
+ operation.mark_completed()
518
+ return "connected", None
519
+ error = int(get_last_error())
520
+ if error == ERROR_IO_PENDING:
521
+ operation.mark_pending()
522
+ return "pending", None
523
+ if error == ERROR_PIPE_CONNECTED:
524
+ # The connection exists even if signaling the event fails.
525
+ operation.mark_completed()
526
+ signaled = bool(bindings.SetEvent(operation.event_handle))
527
+ signal_error = None if signaled else int(get_last_error())
528
+ return "connected", signal_error
529
+ operation.mark_completed()
530
+ return "failed", error
531
+ except BaseException:
532
+ # Any exception before a terminal state leaves submission outcome uncertain.
533
+ if operation.state == operation.STARTING:
534
+ operation.mark_pending()
535
+ raise
536
+
537
+
538
+ def _start_overlapped_io(bindings: Kernel32Bindings, operation: "OverlappedOperation", *, buffer: Any, length: int, write: bool = False, get_last_error: Callable[[], int] = last_error) -> tuple[str, int, int | None]:
539
+ """Start one overlapped ReadFile/WriteFile using operation-owned memory."""
540
+ if operation.state != operation.CREATED:
541
+ raise OverlappedLifecycleError(f"cannot start operation in state {operation.state}")
542
+ if length < 0 or length > MAX_DWORD:
543
+ raise ValueError("I/O length must fit an unsigned Win32 DWORD")
544
+ if buffer is not operation.buffer:
545
+ raise ValueError("I/O buffer must be owned by the operation")
546
+ if length and buffer is None:
547
+ raise ValueError("non-empty I/O requires a live buffer")
548
+ try:
549
+ pointer = ctypes.cast(buffer, LPVOID) if buffer is not None else None
550
+ except (TypeError, ctypes.ArgumentError) as exc:
551
+ raise TypeError("buffer must expose a ctypes-compatible address") from exc
552
+ if not operation.event_handle:
553
+ raise ValueError("overlapped I/O requires an event handle")
554
+ operation.mark_starting()
555
+ operation.overlapped.hEvent = operation.event_handle
556
+ transferred = DWORD(0)
557
+ function = bindings.WriteFile if write else bindings.ReadFile
558
+ try:
559
+ succeeded = bool(function(operation.file_handle, pointer, DWORD(length), ctypes.byref(transferred), ctypes.byref(operation.overlapped)))
560
+ if succeeded:
561
+ operation.mark_completed()
562
+ return "completed", int(transferred.value), None
563
+ error = int(get_last_error())
564
+ if error == ERROR_IO_PENDING:
565
+ operation.mark_pending()
566
+ return "pending", int(transferred.value), error
567
+ operation.mark_completed()
568
+ return "failed", int(transferred.value), error
569
+ except BaseException:
570
+ # Any exception before a terminal state leaves submission outcome uncertain.
571
+ if operation.state == operation.STARTING:
572
+ operation.mark_pending()
573
+ raise
574
+
575
+
576
+ class OverlappedOperation:
577
+ """Own one event, OVERLAPPED object and buffer until I/O is truly complete.
578
+
579
+ Callbacks return (success, error_code) for CancelIoEx and
580
+ (success, bytes_transferred, error_code) for GetOverlappedResultEx. The latter
581
+ must use a bounded wait so a terminal result is obtained before the
582
+ operation releases any memory. ERROR_NOT_FOUND from cancellation is treated
583
+ as a completion race, never as proof that the OVERLAPPED can be freed.
584
+ """
585
+
586
+ CREATED = "created"
587
+ STARTING = "starting"
588
+ PENDING = "pending"
589
+ COMPLETED = "completed"
590
+ CLOSING = "closing"
591
+ CLOSED = "closed"
592
+
593
+ def __init__(
594
+ self,
595
+ *,
596
+ file_handle: Any,
597
+ overlapped: OVERLAPPED,
598
+ event_handle: Any,
599
+ buffer: Any,
600
+ close_handle: Callable[[Any], bool],
601
+ ) -> None:
602
+ if not callable(close_handle):
603
+ raise TypeError("close_handle must be callable")
604
+ self.file_handle = file_handle
605
+ self.overlapped = overlapped
606
+ self.event_handle = event_handle
607
+ self.buffer = buffer
608
+ self._close_handle = close_handle
609
+ self._state = self.CREATED
610
+ self._lock = threading.RLock()
611
+
612
+ @property
613
+ def state(self) -> str:
614
+ with self._lock:
615
+ return self._state
616
+
617
+ def mark_starting(self) -> None:
618
+ """Reserve the operation before entering a Win32 submission call."""
619
+ with self._lock:
620
+ if self._state != self.CREATED:
621
+ raise OverlappedLifecycleError(
622
+ f"cannot start operation in state {self._state}"
623
+ )
624
+ self._state = self.STARTING
625
+
626
+ def mark_pending(self) -> None:
627
+ with self._lock:
628
+ if self._state not in (self.CREATED, self.STARTING):
629
+ raise OverlappedLifecycleError(
630
+ f"cannot mark operation pending in state {self._state}"
631
+ )
632
+ self._state = self.PENDING
633
+
634
+ def mark_completed(self) -> None:
635
+ """Record immediate or drained completion of an overlapped operation."""
636
+ with self._lock:
637
+ if self._state not in (self.CREATED, self.STARTING, self.PENDING):
638
+ raise OverlappedLifecycleError(
639
+ f"cannot complete operation in state {self._state}"
640
+ )
641
+ self._state = self.COMPLETED
642
+
643
+ def cancel_and_drain(
644
+ self,
645
+ *,
646
+ cancel_io_ex: Callable[[Any, OVERLAPPED], tuple[bool, int]],
647
+ get_overlapped_result_ex: Callable[
648
+ [Any, OVERLAPPED, int], tuple[bool, int, int]
649
+ ],
650
+ timeout_ms: int = 5000,
651
+ ) -> OverlappedResult:
652
+ """Request targeted cancellation and drain for at most timeout_ms.
653
+
654
+ A timeout leaves the operation PENDING and retains every resource so
655
+ the caller can retry draining without reusing the OVERLAPPED or buffer.
656
+ """
657
+ if not isinstance(timeout_ms, int) or isinstance(timeout_ms, bool):
658
+ raise TypeError("timeout_ms must be an integer")
659
+ if timeout_ms < 0 or timeout_ms >= INFINITE:
660
+ raise ValueError("timeout_ms must be finite and fit an unsigned Win32 DWORD")
661
+ with self._lock:
662
+ if self._state != self.PENDING:
663
+ raise OverlappedLifecycleError(
664
+ f"cannot cancel operation in state {self._state}"
665
+ )
666
+
667
+ cancel_ok, cancel_error = cancel_io_ex(
668
+ self.file_handle, self.overlapped
669
+ )
670
+ # Always drain, including ERROR_NOT_FOUND: completion may have won
671
+ # the race with cancellation. CancelIoEx itself does not wait.
672
+ result_ok, transferred, result_error = get_overlapped_result_ex(
673
+ self.file_handle, self.overlapped, timeout_ms
674
+ )
675
+ if not result_ok and result_error in (
676
+ ERROR_IO_INCOMPLETE,
677
+ ERROR_IO_PENDING,
678
+ WAIT_TIMEOUT,
679
+ ERROR_INVALID_HANDLE,
680
+ ERROR_INVALID_PARAMETER,
681
+ ):
682
+ raise OverlappedStillPending(
683
+ "bounded GetOverlappedResultEx did not establish terminal completion"
684
+ )
685
+
686
+ self._state = self.COMPLETED
687
+ return OverlappedResult(
688
+ succeeded=bool(result_ok),
689
+ bytes_transferred=int(transferred),
690
+ error_code=0 if result_ok else int(result_error),
691
+ cancel_error=None if cancel_ok else int(cancel_error),
692
+ )
693
+
694
+ def close(self) -> None:
695
+ """Close the event exactly once, but only after I/O is no longer pending."""
696
+ with self._lock:
697
+ if self._state == self.CLOSED:
698
+ return
699
+ if self._state in (self.STARTING, self.PENDING):
700
+ raise OverlappedLifecycleError(
701
+ "cannot release OVERLAPPED resources while I/O submission or completion is in progress"
702
+ )
703
+ # A failed/raising CloseHandle leaves the event handle's validity
704
+ # uncertain. Retain the handle and dependent resources in CLOSING.
705
+ self._state = self.CLOSING
706
+ if self.event_handle:
707
+ if not self._close_handle(self.event_handle):
708
+ raise OSError("CloseHandle failed for overlapped event")
709
+ self.event_handle = None
710
+ self.buffer = None
711
+ self.overlapped = None
712
+ self.file_handle = None
713
+ self._state = self.CLOSED