coakka-http-runtime-python 1.1.2__cp311-abi3-win_amd64.whl

coakka_http/service.py

@@ -0,0 +1,789 @@
+'Bounded request/reply and response-stream service over the Runtime ABI.'
+from __future__ import annotations
+import io
+import queue
+import threading
+import time
+from collections import deque
+from collections.abc import Callable
+from contextlib import contextmanager
+from dataclasses import dataclass,replace
+from functools import partial
+from typing import Final,Iterator,NoReturn,Self,TypeAlias
+from.runtime import InspectionOptions,NativeError,Runtime,plan_service
+from.import _projection as managed_projection
+from._service_cpu import _ServiceCpuOwner
+from.values import TIMEOUT_FOREVER,BodyDelivery,BodyPolicy,Capability,Compression,CpuPolicy,_EMPTY_HEADERS,DrainOutcome,DrainState,EventKind,ExchangeId,FileAuthority,FileResponse,Headers,Health,IoBackend,Limits,Listener,ListenerProtocol,MonitorApplyOutcome,TlsCredentials,TlsReloadOutcome,TlsReloadRequest,MonitorConfig,MonitorEventPage,MonitorOptions,MonitorPolicy,MonitorSnapshot,OutboundId,OutboundIdentity,OutboundRequest,OutboundTarget,OutboundTerminal,OutboundTrust,Request,Response,ResultCode,Route,RouteApiMetadata,RouteSnapshot,RouteRebind,RouteRebindOutcome,RoutePublication,RoutePublicationCode,RoutePublicationOutcome,RuntimeInfo,RuntimeConfig,ServicePlan,SseEvent,StaticMount,TransportSecurity,WebSocketEvent,WebSocketEventKind,WebSocketId
+ResponseStreamProducer=Callable[['ResponseStreamWriter'],Headers]
+ServerSentEventsProducer=Callable[['ServerSentEventsWriter'],None]
+@dataclass(frozen=True,slots=True)
+class StreamingResponse:
+	'Response head plus a bounded single-writer body producer.';producer:ResponseStreamProducer;status:int=200;headers:Headers=_EMPTY_HEADERS
+	def __post_init__(self)->None:
+		'Reject invalid stream declarations before Runtime sees the head.'
+		if not callable(self.producer):raise TypeError('response stream producer is not callable')
+		if isinstance(self.status,bool)or not 100<=self.status<=599:raise ValueError('response status is outside the HTTP range')
+		if not isinstance(self.headers,Headers):raise TypeError('response stream headers must be Headers')
+@dataclass(frozen=True,slots=True)
+class ServerSentEventsResponse:
+	'Runtime-defined SSE head plus a bounded typed event producer.';producer:ServerSentEventsProducer;headers:Headers=_EMPTY_HEADERS
+	def __post_init__(self)->None:
+		'Reject invalid SSE declarations before Runtime sees the head.'
+		if not callable(self.producer):raise TypeError('SSE producer is not callable')
+		if not isinstance(self.headers,Headers):raise TypeError('SSE headers must be Headers')
+WebSocketHandler=Callable[['WebSocketSession',WebSocketEvent],None]
+@dataclass(frozen=True,slots=True)
+class WebSocketResponse:
+	'Declared WebSocket upgrade plus one ordered event handler.';handler:WebSocketHandler;subprotocol:str=''
+	def __post_init__(self)->None:
+		'Validate the callback and optional RFC token before startup.'
+		if not callable(self.handler):raise TypeError('WebSocket handler is not callable')
+		try:encoded=self.subprotocol.encode('ascii','strict')
+		except(AttributeError,UnicodeEncodeError)as error:raise ValueError('WebSocket subprotocol is invalid')from error
+		if len(encoded)>255 or any(byte not in _METHOD_BYTES for byte in encoded):raise ValueError('WebSocket subprotocol is invalid')
+Handler=Callable[[Request],Response|FileResponse|StreamingResponse|ServerSentEventsResponse|WebSocketResponse]
+_METHOD_BYTES:Final=frozenset(b"!#$%&'*+-.^_`|~0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz")
+_DEFAULT_WORKERS:Final=1
+_DEFAULT_QUEUE_CAPACITY:Final=256
+_DEFAULT_RETAINED_BYTES:Final=8<<20
+_DEFAULT_CLOSE_TIMEOUT_MS:Final=30000
+_MAX_WORKERS:Final=1024
+_MAX_ROUTES:Final=1024
+_MAX_HANDLER_BINDINGS:Final=4096
+_MAX_STATIC_MOUNTS:Final=16
+_MAX_FILE_AUTHORITIES:Final=16
+_MAX_OUTBOUND_TARGETS:Final=32
+_MAX_OUTBOUND_TRUSTS:Final=16
+_MAX_OUTBOUND_IDENTITIES:Final=16
+_DEFAULT_HANDLER_BINDINGS:Final=1024
+_ERROR_CAPACITY:Final=64
+_ERROR_DETAIL_BYTES:Final=1024
+class _ResponseStreamState:
+	__slots__='_condition','_terminal','_writable'
+	def __init__(self)->None:'Create one capacity-one writable notification state.';self._condition=threading.Condition();(self._terminal):BaseException|None=None;self._writable=False
+	def grant_writable(self)->None:
+		'Publish initial or post-pressure writable readiness.'
+		with self._condition:
+			if self._terminal is None:self._writable=True
+			self._condition.notify()
+	def terminate(self,error:BaseException)->None:
+		'Wake the writer with the first terminal outcome.'
+		with self._condition:
+			if self._terminal is None:self._terminal=error
+			self._condition.notify()
+	def await_writable(self,timeout_ms:int)->None:
+		'Wait on monotonic time for readiness or terminal failure.';deadline=time.monotonic()+timeout_ms/1000
+		with self._condition:
+			while True:
+				if self._terminal is not None:raise self._terminal
+				if self._writable:self._writable=False;return
+				remaining=deadline-time.monotonic()
+				if remaining<=0:raise TimeoutError('response stream writable-credit wait timed out')
+				self._condition.wait(remaining)
+@dataclass(frozen=True,slots=True)
+class _RequestBodyData:data:bytes
+@dataclass(frozen=True,slots=True)
+class _RequestBodyTrailers:trailers:Headers
+@dataclass(frozen=True,slots=True)
+class _RequestBodyFailure:error:BaseException
+class _RequestBodyEnd:pass
+_REQUEST_BODY_END:Final=_RequestBodyEnd()
+_RequestBodyItem:TypeAlias=_RequestBodyData|_RequestBodyTrailers|_RequestBodyFailure|_RequestBodyEnd
+class _RequestBodyReader(io.RawIOBase):
+	'Sole-reader stream with a bounded copied-event queue.'
+	def __init__(self,request:Request,retained_item_capacity:int,initial_sequence:int)->None:'Adopt one request and reserve its copied-event capacity.';super().__init__();self._request=request;self._capacity=retained_item_capacity;(self._events):queue.Queue[_RequestBodyItem]=queue.Queue(retained_item_capacity+1);self._lock=threading.Lock();self._expected_sequence=initial_sequence+1;self._terminal=False;self._current=b'';self._offset=0;self._eof=False;(self._read_failure):BaseException|None=None
+	def readable(self)->bool:'Report that the handler may read request body bytes.';return True
+	def offer(self,sequence:int,item:_RequestBodyItem)->bool:
+		'Publish one copied Runtime event without blocking the event reader.'
+		with self._lock:
+			if self._terminal:return True
+			if sequence!=self._expected_sequence:self._fail_locked(RuntimeError('request body stream sequence is discontinuous'));return False
+			self._expected_sequence+=1
+			if item is _REQUEST_BODY_END:self._terminal=True;self._events.put_nowait(item);return True
+			if self._events.qsize()>=self._capacity:self._fail_locked(RuntimeError('request body stream queue is full'));return False
+			self._events.put_nowait(item);return True
+	def finish(self,error:BaseException)->None:
+		'Wake a blocked reader with the first terminal failure.'
+		with self._lock:
+			if self._terminal:return
+			self._fail_locked(error)
+	def _fail_locked(self,error:BaseException)->None:
+		self._terminal=True
+		while True:
+			try:self._events.get_nowait()
+			except queue.Empty:break
+		self._events.put_nowait(_RequestBodyFailure(error))
+	def read(self,size:int=-1)->bytes:
+		'Read one available prefix, or all remaining bytes when size is -1.'
+		if size==0:return b''
+		if size<-1:raise ValueError('request body read size is invalid')
+		target=bytearray()
+		while size<0 or len(target)<size:
+			if self._read_failure is not None:raise self._read_failure
+			if self._offset<len(self._current):
+				count=len(self._current)-self._offset
+				if size>=0:count=min(count,size-len(target))
+				target.extend(self._current[self._offset:self._offset+count]);self._offset+=count
+				if self._offset==len(self._current):self._current=b'';self._offset=0
+				if size>=0 and len(target)==size:break
+				continue
+			if self._eof:break
+			item=self._events.get()
+			if isinstance(item,_RequestBodyData):self._current=item.data
+			elif isinstance(item,_RequestBodyTrailers):self._request._set_stream_trailers(item.trailers)
+			elif isinstance(item,_RequestBodyFailure):self._read_failure=item.error
+			elif item is _REQUEST_BODY_END:self._eof=True
+			else:self._read_failure=RuntimeError('unknown request body stream item')
+		return bytes(target)
+	def close(self)->None:'Release the handler reader and wake any concurrent blocked read.';self.finish(RuntimeError('request body stream was closed'));super().close()
+class ResponseStreamWriter:
+	'Single-writer response sink valid only during its producer callback.';__slots__='_closed','_runtime','_exchange','_lock','_state','_timeout_ms'
+	def __init__(self,runtime:Runtime,exchange:ExchangeId,state:_ResponseStreamState,timeout_ms:int)->None:'Borrow one active Runtime exchange for the producer lifetime.';self._runtime=runtime;self._exchange=exchange;self._state=state;self._timeout_ms=timeout_ms;self._lock=threading.Lock();self._closed=False
+	def write(self,data:bytes)->int:
+		'Copy one chunk, retrying pressure only after Runtime recovery credit.'
+		if not isinstance(data,bytes):raise TypeError('response stream chunks must be bytes')
+		if not data:return 0
+		with self._lock:
+			if self._closed:raise RuntimeError('response stream writer is closed')
+			while True:
+				try:self._runtime.write_response_stream(self._exchange,data);return len(data)
+				except NativeError as error:
+					if error.status!=int(ResultCode.CAPACITY_EXHAUSTED):raise
+					self._state.await_writable(self._timeout_ms)
+	def _close(self)->None:
+		with self._lock:self._closed=True
+class ServerSentEventsWriter:
+	'Single-writer SSE sink valid only during its producer callback.';__slots__='_closed','_runtime','_exchange','_lock','_state','_timeout_ms'
+	def __init__(self,runtime:Runtime,exchange:ExchangeId,state:_ResponseStreamState,timeout_ms:int)->None:'Borrow one active SSE exchange for the producer lifetime.';self._runtime=runtime;self._exchange=exchange;self._state=state;self._timeout_ms=timeout_ms;self._lock=threading.Lock();self._closed=False
+	def write(self,event:SseEvent)->None:
+		'Copy one event, retrying pressure only after recovery readiness.'
+		if not isinstance(event,SseEvent):raise TypeError('event must be an SseEvent')
+		with self._lock:
+			if self._closed:raise RuntimeError('SSE writer is closed')
+			while True:
+				try:self._runtime.write_sse(self._exchange,event);return
+				except NativeError as error:
+					if error.status!=int(ResultCode.CAPACITY_EXHAUSTED):raise
+					self._state.await_writable(self._timeout_ms)
+	def _close(self)->None:
+		with self._lock:self._closed=True
+class WebSocketSession:
+	'Generation-safe Service-owned WebSocket session passed to callbacks.';__slots__='_runtime','_id','_lock','_open','subprotocol'
+	def __init__(self,runtime:Runtime,session:WebSocketId,subprotocol:str)->None:'Adopt one opened Runtime session.';self._runtime=runtime;self._id=session;self.subprotocol=subprotocol;self._lock=threading.Lock();self._open=True
+	@property
+	def open(self)->bool:
+		'Return whether this Service still owns an open session.'
+		with self._lock:return self._open
+	def send_text(self,value:str)->None:
+		'Copy one UTF-8 text frame into Runtime.'
+		if not isinstance(value,str):raise TypeError('WebSocket text must be str')
+		self._send(WebSocketEventKind.TEXT,value.encode('utf-8'))
+	def send_bytes(self,value:bytes)->None:
+		'Copy one binary frame into Runtime.'
+		if not isinstance(value,bytes):raise TypeError('WebSocket binary data must be bytes')
+		self._send(WebSocketEventKind.BINARY,value)
+	def ping(self,value:bytes=b'')->None:'Copy one ping control frame into Runtime.';self._send(WebSocketEventKind.PING,value)
+	def pong(self,value:bytes=b'')->None:'Copy one pong control frame into Runtime.';self._send(WebSocketEventKind.PONG,value)
+	def _send(self,kind:WebSocketEventKind,value:bytes)->None:
+		if not isinstance(value,bytes):raise TypeError('WebSocket data must be bytes')
+		with self._lock:
+			if not self._open:raise RuntimeError('WebSocket session is closed')
+			self._runtime.send_websocket(self._id,kind,value)
+	def close(self,code:int=1000,reason:str='')->None:
+		'Start a bounded close handshake.'
+		if not isinstance(reason,str):raise TypeError('WebSocket close reason must be str')
+		encoded_reason=reason.encode('utf-8')
+		with self._lock:
+			if self._open:self._runtime.close_websocket(self._id,code,encoded_reason)
+	def _mark_closed(self)->None:
+		with self._lock:self._open=False
+@dataclass(frozen=True,slots=True)
+class _WebSocketEntry:session:WebSocketSession;response:WebSocketResponse
+class _WebSocketDispatcher:
+	'Own bounded upgrade plans and generation-checked live sessions.';__slots__='_capacity','_closed','_runtime','_errors','_lock','_pending','_sessions'
+	def __init__(self,runtime:Runtime,capacity:int,errors:Callable[[BaseException],None])->None:'Create one sole-reader dispatcher for a started Runtime.';self._runtime=runtime;self._capacity=capacity;self._errors=errors;self._lock=threading.Lock();(self._pending):dict[ExchangeId,WebSocketResponse]={};(self._sessions):dict[WebSocketId,_WebSocketEntry]={};self._closed=False
+	def accept(self,exchange:ExchangeId,response:WebSocketResponse)->None:
+		'Retain one response plan and submit its upgrade to Runtime.'
+		with self._lock:
+			if self._closed or len(self._pending)>=self._capacity:raise RuntimeError('WebSocket upgrade capacity is exhausted')
+			if exchange in self._pending:raise RuntimeError('WebSocket upgrade is already pending')
+			self._pending[exchange]=response
+		try:self._runtime.accept_websocket(exchange,response.subprotocol)
+		except BaseException:
+			with self._lock:self._pending.pop(exchange,None)
+			raise
+	def handle(self,event:WebSocketEvent)->None:
+		'Apply one copied event and invoke its callback outside the lock.';entry:_WebSocketEntry|None=None;diagnostic:BaseException|None=None;close_unowned=False
+		with self._lock:
+			if self._closed:return
+			if event.kind is WebSocketEventKind.ACCEPT_FAILED:self._pending.pop(event.origin_exchange,None);diagnostic=RuntimeError('WebSocket upgrade failed')
+			elif event.kind is WebSocketEventKind.OPEN:
+				response=self._pending.pop(event.origin_exchange,None)
+				if response is None or len(self._sessions)>=self._capacity:close_unowned=True
+				else:session=WebSocketSession(self._runtime,event.session,event.data.decode('utf-8','strict'));entry=_WebSocketEntry(session,response);self._sessions[event.session]=entry
+			else:
+				entry=self._sessions.get(event.session)
+				if entry is not None and event.kind is WebSocketEventKind.CLOSE:self._sessions.pop(event.session,None);entry.session._mark_closed()
+		if diagnostic is not None:self._errors(diagnostic);return
+		if close_unowned:
+			try:self._runtime.close_websocket(event.session,1013,b'upgrade owner unavailable')
+			except BaseException as error:self._errors(error)
+			return
+		if entry is None:return
+		try:entry.response.handler(entry.session,event)
+		except BaseException as error:
+			self._errors(error)
+			try:entry.session.close(1011,'handler failed')
+			except BaseException as close_error:self._errors(close_error)
+	def shutdown(self)->None:
+		'Reject new upgrades and invalidate all language-owned sessions.'
+		with self._lock:self._closed=True;self._pending.clear();sessions=tuple(self._sessions.values());self._sessions.clear()
+		for entry in sessions:entry.session._mark_closed()
+class ServiceError(RuntimeError):
+	'Bounded Python-owned diagnostic retained by :class:`Service`.'
+	def __init__(self,original_type:str,detail:str)->None:'Create a traceback-free diagnostic from bounded copied text.';self.original_type=original_type;self.detail=detail;super().__init__(f"{original_type}: {detail}"if detail else original_type)
+class ServiceCloseError(RuntimeError):
+	'Core did not drain gracefully; cleanup success does not erase this cause.'
+	def __init__(self,outcome:DrainOutcome,*,runtime_retained:bool)->None:"Keep Core's typed observation and whether cleanup can be retried.";self.outcome=outcome;self.runtime_retained=runtime_retained;super().__init__(f"Core drain did not complete gracefully (state={outcome.state})")
+class ServiceStartError(RuntimeError):
+	'Failed startup plus failed cleanup, retaining the exact retry owner.'
+	def __init__(self,startup_error:BaseException,cleanup_error:BaseException,runtime:Runtime)->None:"Preserve both causes; call this error's close() to retry all owners.";self.startup_error=startup_error;self.cleanup_error=cleanup_error;self.runtime=runtime;(self._cpu_owner):_ServiceCpuOwner|None=None;super().__init__('service startup and cleanup both failed; runtime retained')
+	def close(self,timeout_ms:int=30000)->None:
+		'Retry cleanup, then join the retained CPU owner with a finite budget.'
+		if isinstance(timeout_ms,bool)or not isinstance(timeout_ms,int)or not 1<=timeout_ms<=60000:raise ValueError('close timeout is invalid')
+		deadline=time.monotonic()+timeout_ms/1000;self.runtime.close()
+		if self._cpu_owner is not None:self._cpu_owner.close(max(.0,deadline-time.monotonic()))
+def _retired_submission(error:BaseException)->bool:'Recognize only explicit native retirement, without connector inference.';return isinstance(error,NativeError)and error.status in(int(ResultCode.CLOSED),int(ResultCode.STALE_EXCHANGE))
+_WorkItem:TypeAlias=tuple[Handler,Request,int]
+class Builder:
+	'Single-use builder for one bounded native-owned HTTP service.\n\n    The facade copies a leased request into Python-owned values, releases the\n    native lease, and then admits the request to a finite Python worker queue.\n    Request/response streaming, SSE, WebSocket and handler publication are\n    available directly on this facade, including logical-target outbound calls.\n    ';__slots__='_close_timeout_ms','_compression','_cpu_policy','_file_authorities','_handlers','_limits','_listener','_io_backend','_max_handler_bindings','_max_retained_bytes','_monitor_options','_next_route_id','_outbound_identities','_outbound_targets','_outbound_trusts','_queue_capacity','_routes','_started','_static_mounts','_websocket_routes','_workers'
+	def __init__(self)->None:'Create a loopback HTTP/1.1 builder with finite dispatch defaults.';self._listener=Listener();self._compression=Compression();self._cpu_policy=CpuPolicy.AUTO;self._io_backend=IoBackend.PLATFORM_DEFAULT;self._limits=Limits();self._workers=_DEFAULT_WORKERS;self._websocket_routes=0;self._queue_capacity=_DEFAULT_QUEUE_CAPACITY;self._max_retained_bytes=_DEFAULT_RETAINED_BYTES;self._max_handler_bindings=_DEFAULT_HANDLER_BINDINGS;(self._monitor_options):MonitorOptions|None=None;self._close_timeout_ms=_DEFAULT_CLOSE_TIMEOUT_MS;(self._routes):list[Route]=[];(self._static_mounts):list[StaticMount]=[];(self._file_authorities):list[FileAuthority]=[];(self._outbound_targets):list[OutboundTarget]=[];(self._outbound_trusts):list[tuple[int,bytes]]=[];(self._outbound_identities):list[tuple[int,bytes,bytes]]=[];(self._handlers):dict[int,Handler]={};self._next_route_id=1;self._started=False
+	def listener(self,listener:Listener)->Self:
+		'Set the complete listener declaration, including TLS fields.';self._ensure_mutable()
+		if not isinstance(listener,Listener):raise TypeError('listener must be a Listener value')
+		self._listener=listener;return self
+	def listen(self,host:str,port:int)->Self:
+		'Replace only the bind address and port of the current listener.';self._ensure_mutable()
+		if not isinstance(host,str)or not host.strip()or'\x00'in host:raise ValueError('listener host is invalid')
+		if isinstance(port,bool)or not isinstance(port,int)or not 0<=port<=65535:raise ValueError('listener port is invalid')
+		self._listener=replace(self._listener,bind_address=host,port=port);return self
+	def concurrency(self,workers:int)->Self:
+		'Set the finite number of Python handler worker threads.';self._ensure_mutable()
+		if isinstance(workers,bool)or not isinstance(workers,int)or not 1<=workers<=_MAX_WORKERS:raise ValueError('worker count is invalid')
+		self._workers=workers;return self
+	def cpu(self,policy:CpuPolicy)->Self:
+		"Submit Core placement intent; AUTO prefers two allowed logical CPUs.\n\n        This does not set worker count, remove the GIL or impose a process quota.\n        The dedicated lifecycle owner and its children are the only scope.\n        Runtime info reports Core's actual selection or unsupported placement.\n        ";self._ensure_mutable()
+		if not isinstance(policy,CpuPolicy):raise TypeError('policy must be a CpuPolicy')
+		self._cpu_policy=policy;return self
+	def dispatch_queue(self,capacity:int)->Self:
+		'Set the bounded copied-request queue capacity.';self._ensure_mutable()
+		if isinstance(capacity,bool)or not isinstance(capacity,int)or not 1<=capacity<=(1<<31)-1:raise ValueError('dispatch queue capacity is invalid')
+		self._queue_capacity=capacity;return self
+	def dispatch_bytes(self,maximum:int)->Self:
+		'Set the aggregate byte ceiling for queued and running requests.';self._ensure_mutable()
+		if isinstance(maximum,bool)or not isinstance(maximum,int)or not 1<=maximum<=(1<<63)-1:raise ValueError('dispatch byte capacity is invalid')
+		self._max_retained_bytes=maximum;return self
+	def handler_bindings(self,maximum:int)->Self:
+		'Set the total lifetime capacity for single-assignment handler IDs.';self._ensure_mutable()
+		if isinstance(maximum,bool)or not isinstance(maximum,int)or not 1<=maximum<=_MAX_HANDLER_BINDINGS:raise ValueError('handler binding capacity is invalid')
+		self._max_handler_bindings=maximum;return self
+	def close_timeout(self,timeout_ms:int)->Self:
+		'Set the monotonic facade drain/join timeout in milliseconds.';self._ensure_mutable()
+		if isinstance(timeout_ms,bool)or not isinstance(timeout_ms,int)or not 1<=timeout_ms<=60000:raise ValueError('close timeout is invalid')
+		self._close_timeout_ms=timeout_ms;return self
+	def limits(self,limits:Limits)->Self:
+		'Replace the complete construction-time Runtime resource ceilings.';self._ensure_mutable()
+		if not isinstance(limits,Limits):raise TypeError('limits must be a Limits value')
+		self._limits=limits;return self
+	def monitor(self,options:MonitorOptions)->Self:
+		'Reserve bounded Runtime monitor storage and its initial policy.';self._ensure_mutable()
+		if not isinstance(options,MonitorOptions):raise TypeError('monitor must be a MonitorOptions value')
+		self._monitor_options=options;return self
+	def compression(self,policy:Compression)->Self:
+		'Set the bounded native response-compression policy.';self._ensure_mutable()
+		if not isinstance(policy,Compression):raise TypeError('policy must be a Compression value')
+		self._compression=policy;return self
+	def io_backend(self,backend:IoBackend)->Self:
+		'Opt in to a native backend request; the default remains platform I/O.';self._ensure_mutable()
+		if not isinstance(backend,IoBackend):raise TypeError('backend must be an IoBackend value')
+		self._io_backend=backend;return self
+	def static_mount(self,mount:StaticMount)->Self:
+		'Add one Runtime-owned static tree with optional index and SPA policy.';self._ensure_mutable()
+		if not isinstance(mount,StaticMount):raise TypeError('mount must be a StaticMount value')
+		if len(self._static_mounts)>=_MAX_STATIC_MOUNTS:raise ValueError('static mount count exceeds the Runtime bound')
+		self._static_mounts.append(mount);return self
+	def file_authority(self,authority:FileAuthority)->Self:
+		'Add one bounded root for application-selected file responses.';self._ensure_mutable()
+		if not isinstance(authority,FileAuthority):raise TypeError('authority must be a FileAuthority value')
+		if len(self._file_authorities)>=_MAX_FILE_AUTHORITIES:raise ValueError('file authority count exceeds the Runtime bound')
+		self._file_authorities.append(authority);return self
+	def outbound_target(self,target:OutboundTarget)->Self:
+		'Add one immutable logical outbound target generation.';self._ensure_mutable()
+		if not isinstance(target,OutboundTarget):raise TypeError('target must be an OutboundTarget value')
+		if len(self._outbound_targets)>=_MAX_OUTBOUND_TARGETS:raise ValueError('outbound target count exceeds the Runtime bound')
+		self._outbound_targets.append(target);return self
+	def outbound_trust(self,generation:int,ca_pem:bytes)->Self:
+		'Add one generation-keyed outbound CA bundle copied by Runtime.';self._ensure_mutable()
+		if len(self._outbound_trusts)>=_MAX_OUTBOUND_TRUSTS:raise ValueError('outbound trust count exceeds the Runtime bound')
+		if isinstance(generation,bool)or generation<=0 or not ca_pem:raise ValueError('outbound trust is invalid')
+		self._outbound_trusts.append((generation,bytes(ca_pem)));return self
+	def outbound_identity(self,generation:int,certificate_chain_pem:bytes,private_key_pem:bytes)->Self:
+		'Add one outbound mutual-TLS identity generation copied by Runtime.';self._ensure_mutable()
+		if len(self._outbound_identities)>=_MAX_OUTBOUND_IDENTITIES:raise ValueError('outbound identity count exceeds the Runtime bound')
+		if isinstance(generation,bool)or generation<=0 or not certificate_chain_pem or not private_key_pem:raise ValueError('outbound identity is invalid')
+		self._outbound_identities.append((generation,bytes(certificate_chain_pem),bytes(private_key_pem)));return self
+	def add_route(self,route:Route,handler:Handler)->Self:
+		'Register an explicit route and its Python handler binding.';self._ensure_mutable()
+		if not isinstance(route,Route):raise TypeError('route must be a Route value')
+		if not callable(handler):raise TypeError('route handler is not callable')
+		if len(self._routes)>=_MAX_ROUTES:raise ValueError('route count exceeds the facade bound')
+		binding_id=route.handler_binding_id or route.id
+		if binding_id<=0 or binding_id in self._handlers:raise ValueError('handler binding identity is invalid or duplicated')
+		if any(existing.id==route.id for existing in self._routes):raise ValueError('route identity is duplicated')
+		effective=replace(route,handler_binding_id=binding_id);self._routes.append(effective);self._handlers[binding_id]=handler;self._next_route_id=max(self._next_route_id,route.id+1);return self
+	def route(self,method:str,pattern:str,handler:Handler,*,body_delivery:BodyDelivery=BodyDelivery.INLINE,body_policy:BodyPolicy|None=None)->Self:
+		'Register a generated-identity route and handler.';self._ensure_mutable();normalized=method.strip().upper()if isinstance(method,str)else''
+		try:method_bytes=normalized.encode('ascii','strict')
+		except UnicodeEncodeError as error:raise ValueError('route method is invalid')from error
+		if not method_bytes or any(byte not in _METHOD_BYTES for byte in method_bytes):raise ValueError('route method is invalid')
+		if not isinstance(pattern,str)or not pattern.startswith('/')or'\x00'in pattern:raise ValueError('route pattern is invalid')
+		if not isinstance(body_delivery,BodyDelivery):raise TypeError('body_delivery must be a BodyDelivery value')
+		policy=BodyPolicy()if body_policy is None else body_policy
+		if not isinstance(policy,BodyPolicy):raise TypeError('body_policy must be a BodyPolicy value')
+		route=Route(id=self._next_route_id,method=normalized,pattern=pattern,handler_binding_id=self._next_route_id,body_delivery=body_delivery,body_policy=policy);return self.add_route(route,handler)
+	def document(self,metadata:RouteApiMetadata)->Self:
+		'Attach immutable documentation to the most recently added route.';self._ensure_mutable()
+		if not isinstance(metadata,RouteApiMetadata):raise TypeError('metadata must be a RouteApiMetadata value')
+		if not self._routes:raise ValueError('route documentation requires a preceding route')
+		self._routes[-1]=replace(self._routes[-1],api_metadata=metadata);return self
+	def get(self,pattern:str,handler:Handler)->Self:'Register a buffered GET route.';return self.route('GET',pattern,handler)
+	def post(self,pattern:str,handler:Handler)->Self:'Register a buffered POST route.';return self.route('POST',pattern,handler)
+	def put(self,pattern:str,handler:Handler)->Self:'Register a buffered PUT route.';return self.route('PUT',pattern,handler)
+	def patch(self,pattern:str,handler:Handler)->Self:'Register a buffered PATCH route.';return self.route('PATCH',pattern,handler)
+	def delete(self,pattern:str,handler:Handler)->Self:'Register a buffered DELETE route.';return self.route('DELETE',pattern,handler)
+	def websocket(self,pattern:str,handler:Handler)->Self:
+		'Register one declared GET WebSocket upgrade route.';before=len(self._routes);self.route('GET',pattern,handler)
+		if len(self._routes)==before+1:self._routes[-1]=replace(self._routes[-1],websocket=True);self._websocket_routes+=1
+		return self
+	def route_stream(self,method:str,pattern:str,handler:Handler,*,body_policy:BodyPolicy|None=None)->Self:'Register a generated-identity incremental request-body route.';return self.route(method,pattern,handler,body_delivery=BodyDelivery.STREAM,body_policy=body_policy)
+	def get_stream(self,pattern:str,handler:Handler)->Self:'Register a streamed GET request-body handler.';return self.route_stream('GET',pattern,handler)
+	def post_stream(self,pattern:str,handler:Handler)->Self:'Register a streamed POST request-body handler.';return self.route_stream('POST',pattern,handler)
+	def put_stream(self,pattern:str,handler:Handler)->Self:'Register a streamed PUT request-body handler.';return self.route_stream('PUT',pattern,handler)
+	def patch_stream(self,pattern:str,handler:Handler)->Self:'Register a streamed PATCH request-body handler.';return self.route_stream('PATCH',pattern,handler)
+	def delete_stream(self,pattern:str,handler:Handler)->Self:'Register a streamed DELETE request-body handler.';return self.route_stream('DELETE',pattern,handler)
+	def start(self,*,inspection:InspectionOptions|None=None)->Service:'Start native admission, bounded dispatch, and optional inspection.';self._ensure_mutable();start=self._start_native if inspection is None else partial(self._start_native,inspection=inspection);return _ServiceCpuOwner(self._cpu_policy).start(start,self._close_timeout_ms)
+	def _start_native(self,*,inspection:InspectionOptions|None=None)->Service:
+		if managed_projection.PROJECTION is None:raise RuntimeError('managed service requires its native projection image')
+		if not self._routes and not self._static_mounts and not self._outbound_targets:raise ValueError('at least one route, static mount, or outbound target is required')
+		if not self._outbound_targets and(self._outbound_trusts or self._outbound_identities):raise ValueError('outbound options and credentials require a logical target')
+		if len(self._handlers)>self._max_handler_bindings:raise ValueError('route count exceeds the handler binding capacity')
+		self._started=True;required=Capability.INBOUND|Capability.ROUTE_REBIND|Capability.ROUTE_PUBLICATION|Capability.HEALTH|Capability.RESPONSE_STREAM|Capability.RESPONSE_TRAILERS|Capability.RESPONSE_WRITE_TIMEOUT|Capability.SERVER_SENT_EVENTS
+		if any(route.body_delivery is BodyDelivery.STREAM for route in self._routes):required|=Capability.REQUEST_STREAM
+		if self._listener.protocol is ListenerProtocol.HTTP_2:required|=Capability.HTTP_2
+		elif self._listener.protocol is ListenerProtocol.HTTP_3:required|=Capability.HTTP_3
+		if self._listener.security is TransportSecurity.TLS:required|=Capability.TLS
+		elif self._listener.security is TransportSecurity.MUTUAL_TLS:required|=Capability.MUTUAL_TLS
+		if self._monitor_options is not None:required|=Capability.MONITOR
+		if self._websocket_routes:required|=Capability.WEBSOCKET
+		if self._static_mounts:required|=Capability.STATIC_FILES|Capability.STATIC_FRONTEND
+		if self._file_authorities:required|=Capability.APPLICATION_FILES
+		if self._outbound_targets:required|=Capability.OUTBOUND|Capability.OUTBOUND_LOGICAL_TARGET
+		plan=plan_service(required)
+		if not plan.supported:raise RuntimeError(f"Runtime cannot provide the declared service (missing={int(plan.missing_capabilities):#x})")
+		create_runtime=Runtime if inspection is None else partial(Runtime,inspection=inspection);runtime=create_runtime(RuntimeConfig(listener=self._listener,routes=tuple(self._routes),limits=self._limits,monitor=self._monitor_options or MonitorOptions(),static_mounts=tuple(self._static_mounts),file_authorities=tuple(self._file_authorities),compression=self._compression,io_backend=self._io_backend,outbound_targets=tuple(self._outbound_targets),outbound_trusts=tuple(OutboundTrust(generation,ca_pem)for(generation,ca_pem)in self._outbound_trusts),outbound_identities=tuple(OutboundIdentity(generation,certificate,key)for(generation,certificate,key)in self._outbound_identities),omit_buffered_success_events=True))
+		try:accepted=runtime.effective_limits();runtime.start();return Service(runtime,dict(self._handlers),tuple(self._routes),plan=plan,worker_count=self._workers,queue_capacity=self._queue_capacity,max_retained_bytes=self._max_retained_bytes,max_handler_bindings=self._max_handler_bindings,close_timeout_ms=self._close_timeout_ms,response_write_timeout_ms=accepted.response_write_timeout_ms,request_stream_capacity=accepted.request_stream_max_retained_items,web_socket_capacity=accepted.max_active_requests if self._websocket_routes else 0)
+		except BaseException as startup_error:
+			try:runtime.close()
+			except BaseException as cleanup_error:raise ServiceStartError(startup_error,cleanup_error,runtime)from startup_error
+			raise
+	def _ensure_mutable(self)->None:
+		if self._started:raise RuntimeError('builder has already started a service')
+class Service:
+	'Lifecycle owner for a Runtime plus one reader and finite worker set.';__slots__='_close_lock','_close_serial','_close_timeout_ms','_closed','_closed_error','_cpu_owner','_draining','_runtime','_error_lock','_errors','_handler_lock','_handlers','_max_handler_bindings','_monitor_condition','_monitor_waits','_outbound_condition','_outbound_waits','_retention_lock','_plan','_queue','_reader','_request_stream_capacity','_request_stream_lock','_request_streams','_response_stream_lock','_response_streams','_response_write_timeout_ms','_drain_outcome','_workers_signalled','_retained_byte_capacity','_retained_bytes','_routes','_stopping','_web_socket_dispatcher','_web_socket_reader','_workers'
+	def __init__(self,runtime:Runtime,handlers:dict[int,Handler],routes:tuple[Route,...],*,plan:ServicePlan,worker_count:int,queue_capacity:int,max_retained_bytes:int,max_handler_bindings:int,close_timeout_ms:int,response_write_timeout_ms:int,request_stream_capacity:int,web_socket_capacity:int)->None:
+		'Adopt a started Runtime and start its sole inbound reader.';self._runtime=runtime;(self._cpu_owner):_ServiceCpuOwner|None=None;self._handlers=handlers;self._handler_lock=threading.Lock();self._max_handler_bindings=max_handler_bindings;self._routes=routes;self._plan=plan;(self._queue):queue.Queue[_WorkItem|None]=queue.Queue(queue_capacity);self._stopping=threading.Event();self._draining=threading.Event();self._close_lock=threading.Lock();self._close_serial=threading.Lock();self._error_lock=threading.Lock();self._retention_lock=threading.Lock();self._monitor_condition=threading.Condition();self._outbound_condition=threading.Condition();(self._errors):deque[ServiceError]=deque(maxlen=_ERROR_CAPACITY);self._retained_bytes=0;self._retained_byte_capacity=max_retained_bytes;self._response_stream_lock=threading.Lock();(self._response_streams):dict[ExchangeId,_ResponseStreamState]={};self._response_write_timeout_ms=response_write_timeout_ms;(self._drain_outcome):DrainOutcome|None=None;self._workers_signalled=0;self._request_stream_lock=threading.Lock();(self._request_streams):dict[ExchangeId,_RequestBodyReader]={};self._request_stream_capacity=request_stream_capacity;self._monitor_waits=0;self._outbound_waits=0;self._web_socket_dispatcher=_WebSocketDispatcher(runtime,web_socket_capacity,self._record)if web_socket_capacity else None;self._closed=False;(self._closed_error):BaseException|None=None;self._close_timeout_ms=close_timeout_ms;self._reader=threading.Thread(target=self._read_events,name='coakka-http-events');self._workers=tuple(threading.Thread(target=self._run_worker,name=f"coakka-http-handler-{index}")for index in range(worker_count));self._web_socket_reader=threading.Thread(target=self._read_web_sockets,name='coakka-http-websocket-events')if self._web_socket_dispatcher is not None else None;started:list[threading.Thread]=[]
+		try:
+			for worker in self._workers:worker.start();started.append(worker)
+			self._reader.start();started.append(self._reader)
+			if self._web_socket_reader is not None:self._web_socket_reader.start();started.append(self._web_socket_reader)
+		except BaseException:
+			self._stopping.set();worker_count=sum(thread in self._workers for thread in started)
+			for _worker in range(worker_count):self._queue.put(None)
+			if self._reader in started:self._runtime.interrupt()
+			for thread in started:thread.join()
+			raise
+	@property
+	def port(self)->int:
+		'Return the actual bound port of the native listener.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self._runtime.port
+	@property
+	def routes(self)->RouteSnapshot:
+		"Pull Core's coherent immutable route cut independently of monitoring.\n\n        Inspection failure propagates; local handler-retention declarations\n        never substitute for effective Core state.\n        "
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self._runtime.route_snapshot()
+	@property
+	def plan(self)->ServicePlan:"Return Runtime's provider decision captured before listener startup.";return self._plan
+	def health(self)->Health:
+		'Copy the current Runtime health snapshot.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self._runtime.health()
+	def runtime_info(self)->RuntimeInfo:
+		'Copy capability and effective backend truth from Runtime.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return replace(self._runtime.runtime_info(),cpu=self._cpu_owner.info if self._cpu_owner is not None else None)
+	def effective_limits(self)->Limits:
+		"Copy Core's accepted startup ceilings and deadlines unchanged."
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self._runtime.effective_limits()
+	def probe_liveness(self,timeout_ms:int=1000)->Health:
+		'Wait for fresh Runtime progress evidence within ``timeout_ms``.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self._runtime.probe_liveness(timeout_ms)
+	def outbound_submit(self,request:OutboundRequest)->OutboundId:
+		'Submit one buffered call to a startup-declared logical target.'
+		with self._close_lock:
+			if self._closed or self._stopping.is_set():raise RuntimeError('service is closing or closed')
+			return self._runtime.outbound_submit(request)
+	def outbound_cancel(self,call:OutboundId)->None:
+		'Request cancellation of an admitted outbound call.'
+		with self._close_lock:
+			if self._closed or self._stopping.is_set():raise RuntimeError('service is closing or closed')
+			self._runtime.outbound_cancel(call)
+	def take_outbound(self,timeout_ms:int=TIMEOUT_FOREVER)->OutboundTerminal|None:
+		'Wait without holding the lifecycle lock and copy one terminal.'
+		with self._close_lock:
+			if self._closed or self._stopping.is_set():raise RuntimeError('service is closing or closed')
+			runtime=self._runtime
+			with self._outbound_condition:self._outbound_waits+=1
+		try:return runtime.take_outbound(timeout_ms)
+		finally:
+			with self._outbound_condition:self._outbound_waits-=1;self._outbound_condition.notify_all()
+	def tls_credentials(self)->TlsCredentials:
+		'Read the effective credential generation of this secure service.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self._runtime.tls_credentials()
+	def tls_reload(self,request:TlsReloadRequest)->TlsReloadOutcome:
+		"Submit a TLS credential replacement and return Core's outcome."
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self._runtime.tls_reload(request)
+	def monitor_config(self)->MonitorConfig:
+		'Return the effective pointer-free monitor configuration.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self._runtime.monitor_config()
+	def monitor_snapshot(self)->MonitorSnapshot:
+		'Return a bounded aggregate monitor snapshot safe to retain.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self._runtime.monitor_snapshot()
+	def monitor_apply(self,expected_generation:int,policy:MonitorPolicy)->MonitorApplyOutcome:
+		'Apply a live policy and return its typed outcome.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self._runtime.monitor_apply(expected_generation,policy)
+	def monitor_read(self,after_sequence:int,maximum_events:int)->MonitorEventPage:
+		'Copy a bounded page of newer operational monitor events.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self._runtime.monitor_read(after_sequence,maximum_events)
+	def monitor_wait(self,timeout_ms:int)->bool:
+		'Wait without holding the lifecycle lock; false means timeout.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			runtime=self._runtime
+			with self._monitor_condition:self._monitor_waits+=1
+		try:return runtime.monitor_wait(timeout_ms)
+		finally:
+			with self._monitor_condition:self._monitor_waits-=1;self._monitor_condition.notify_all()
+	def monitor_interrupt(self)->None:
+		'Wake the sole blocking monitor waiter.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			self._runtime.monitor_interrupt()
+	def prepare_handler(self,binding_id:int,handler:Handler)->None:
+		'Register one single-assignment binding without publishing it.'
+		if isinstance(binding_id,bool)or not isinstance(binding_id,int)or binding_id<=0 or not callable(handler):raise ValueError('handler binding is invalid')
+		with self._close_lock:
+			if self._closed or self._stopping.is_set():raise RuntimeError('service is closing or closed')
+			with self._handler_lock:
+				if binding_id in self._handlers:raise ValueError('handler binding identity was already used')
+				if len(self._handlers)>=self._max_handler_bindings:raise RuntimeError('handler binding capacity is exhausted')
+				self._handlers[binding_id]=handler
+	def rebind_handler(self,request:RouteRebind)->RouteRebindOutcome:
+		"Submit a bounded binding update and return Core's effective outcome.\n\n        The public operation is synchronous; it does not expose a separate\n        caller timeout or imply cancellation of an accepted publication.\n        "
+		if not isinstance(request,RouteRebind):raise TypeError('request must be a RouteRebind')
+		with self._close_lock:
+			if self._closed or self._stopping.is_set():raise RuntimeError('service is closing or closed')
+			with self._handler_lock:prepared=request.new_handler_binding_id in self._handlers
+			if not prepared:raise ValueError('handler binding was not prepared')
+			outcome=self._runtime.rebind(request)
+			if outcome.code is RoutePublicationCode.APPLIED and self._current_control_cut(outcome.replayed,outcome.route_generation,outcome.binding_change_sequence):self._routes=tuple(replace(route,handler_binding_id=outcome.effective_handler_binding_id)if route.id==outcome.route_id else route for route in self._routes)
+			return outcome
+	def _current_control_cut(self,replayed:bool,generation:int,sequence:int,metadata_generation:int|None=None)->bool:
+		if not replayed:return True
+		current=self._runtime.route_snapshot().identity;return current.route_generation==generation and current.binding_change_sequence==sequence and(metadata_generation is None or current.metadata_generation==metadata_generation)
+	def publish_routes(self,request:RoutePublication)->RoutePublicationOutcome:
+		"Submit a complete generation and return Core's synchronous outcome."
+		if not isinstance(request,RoutePublication):raise TypeError('request must be a RoutePublication')
+		routes=tuple(replace(route,handler_binding_id=route.handler_binding_id or route.id)for route in request.routes)
+		if len(routes)>self._max_handler_bindings:raise ValueError('route generation exceeds the service bound')
+		with self._close_lock:
+			if self._closed or self._stopping.is_set():raise RuntimeError('service is closing or closed')
+			with self._handler_lock:
+				if any(route.handler_binding_id not in self._handlers for route in routes):raise ValueError('route references an unprepared handler binding')
+			outcome=self._runtime.publish_routes(replace(request,routes=routes))
+			if outcome.code is RoutePublicationCode.APPLIED and self._current_control_cut(outcome.replayed,outcome.effective_route_generation,outcome.effective_binding_change_sequence,outcome.effective_metadata_generation):self._routes=routes
+			return outcome
+	def poll_error(self)->ServiceError|None:
+		'Remove the oldest bounded reader, handler, or submission error.'
+		with self._error_lock:return self._errors.popleft()if self._errors else None
+	def close(self,timeout_ms:int|None=None)->None:
+		"Observe Core drain, stop native work, join Python owners, then destroy.\n\n        A caller wait expiry retains the owner for retry. Core EXPIRED/ABORTED/\n        FAILED stays a ServiceCloseError even after cleanup and repeated close.\n        Call from an external lifecycle owner, never from this service's handler\n        or reader. Arbitrary Python code cannot be safely force-cancelled.\n        ";timeout=self._close_timeout_ms if timeout_ms is None else timeout_ms
+		if isinstance(timeout,bool)or not isinstance(timeout,int)or not 1<=timeout<=60000:raise ValueError('close timeout is invalid')
+		if threading.current_thread()in(*self._workers,self._reader,self._web_socket_reader):raise RuntimeError("close must run outside this service's reader/handler threads")
+		with self._close_attempt(timeout)as deadline:
+			if self._closed:
+				if self._closed_error is not None:raise self._closed_error
+				self._raise_drain_failure(runtime_retained=False);return
+			if not self._stopping.is_set():
+				with self._close_lock:
+					if not self._draining.is_set():self._runtime.drain();self._draining.set()
+				remaining_ms=max(0,int((deadline-time.monotonic())*1000));self._drain_outcome=self._runtime.wait_drained(remaining_ms)
+				if self._drain_outcome.state is DrainState.PENDING:raise TimeoutError('timed out draining Python service')
+				try:self._runtime.stop()
+				except BaseException as error:self._raise_cleanup_failure(error)
+				self._stopping.set();self._finish_request_streams(RuntimeError('service has stopped'))
+				with self._response_stream_lock:
+					for state in self._response_streams.values():state.terminate(NativeError(int(ResultCode.CLOSED),'Core has stopped'))
+			with self._outbound_condition:
+				while self._outbound_waits!=0:
+					remaining=deadline-time.monotonic()
+					if remaining<=0:raise TimeoutError('timed out stopping outbound waiter')
+					self._outbound_condition.wait(remaining)
+			with self._monitor_condition:
+				while self._monitor_waits!=0:
+					remaining=deadline-time.monotonic()
+					if remaining<=0:raise TimeoutError('timed out stopping monitor waiter')
+					self._monitor_condition.wait(remaining)
+			self._join(self._reader,deadline,'Runtime event reader')
+			if self._web_socket_reader is not None:self._join(self._web_socket_reader,deadline,'Runtime WebSocket reader')
+			while self._workers_signalled<len(self._workers):
+				remaining=deadline-time.monotonic()
+				if remaining<=0:raise TimeoutError('timed out stopping Python handler workers')
+				try:self._queue.put(None,timeout=remaining);self._workers_signalled+=1
+				except queue.Full as error:raise TimeoutError('timed out stopping Python handler workers')from error
+			for worker in self._workers:self._join(worker,deadline,'Python handler worker')
+			with self._close_lock:
+				try:self._runtime.close()
+				except BaseException as error:self._raise_cleanup_failure(error)
+				if self._web_socket_dispatcher is not None:self._web_socket_dispatcher.shutdown()
+			try:
+				if self._cpu_owner is not None:self._cpu_owner.close(max(.0,deadline-time.monotonic()))
+			except TimeoutError:raise
+			except BaseException as cleanup_error:
+				try:self._raise_drain_failure(runtime_retained=False)
+				except ServiceCloseError as drain_error:self._closed_error=BaseExceptionGroup('drain and CPU cleanup failed',[drain_error,cleanup_error])
+				else:self._closed_error=cleanup_error
+				with self._close_lock:self._closed=True
+				raise self._closed_error
+			with self._close_lock:self._closed=True
+			self._raise_drain_failure(runtime_retained=False)
+	@contextmanager
+	def _close_attempt(self,timeout_ms:int)->Iterator[float]:
+		"Include waiting behind another close in this caller's finite budget.";deadline=time.monotonic()+timeout_ms/1000
+		if not self._close_serial.acquire(timeout=timeout_ms/1000):raise TimeoutError('timed out waiting for another close attempt')
+		try:yield deadline
+		finally:self._close_serial.release()
+	def _raise_drain_failure(self,*,runtime_retained:bool)->None:
+		if self._drain_outcome is not None and(self._drain_outcome.state is not DrainState.COMPLETE or self._drain_outcome.status!=int(ResultCode.OK)):raise ServiceCloseError(self._drain_outcome,runtime_retained=runtime_retained)
+	def _raise_cleanup_failure(self,cleanup_error:BaseException)->NoReturn:
+		'Keep a refused cleanup owner and both independent causal failures.'
+		try:self._raise_drain_failure(runtime_retained=True)
+		except ServiceCloseError as drain_error:raise BaseExceptionGroup('drain and native cleanup failed',[drain_error,cleanup_error])from None
+		raise cleanup_error
+	def __enter__(self)->Self:
+		'Return this running service for scoped ownership.'
+		with self._close_lock:
+			if self._closed:raise RuntimeError('service is closed')
+			return self
+	def __exit__(self,_type:object,_value:object,_traceback:object)->None:'Drain and destroy this service on scope exit.';self.close()
+	def _record(self,error:BaseException)->None:
+		original_type=type(error).__name__[:128]
+		try:encoded=str(error).encode('utf-8','replace')[:_ERROR_DETAIL_BYTES];detail=encoded.decode('utf-8','replace')
+		except BaseException:detail='diagnostic conversion failed'
+		with self._error_lock:self._errors.append(ServiceError(original_type,detail))
+	def _read_events(self)->None:
+		try:
+			with self._runtime._service_event_reader()as native_service:
+				while not self._stopping.is_set():
+					item=self._runtime._take_service_event_borrowed(native_service)
+					if item is None:continue
+					if isinstance(item,tuple):request,sequence,retained_bytes=item;self._open_request_stream(request,sequence);self._admit(request,retained_bytes);continue
+					if item.kind in(EventKind.TERMINAL,EventKind.REQUEST_CANCELLED):self._signal_response_stream(item.kind,item.exchange);self._signal_request_stream(item.kind,item.exchange,item.sequence,None)
+					elif item.kind is EventKind.REQUEST_DATA:self._signal_request_stream(item.kind,item.exchange,item.sequence,_RequestBodyData(item.data))
+					elif item.kind is EventKind.REQUEST_TRAILERS:self._signal_request_stream(item.kind,item.exchange,item.sequence,_RequestBodyTrailers(item.stream_trailers))
+					elif item.kind is EventKind.REQUEST_END:self._signal_request_stream(item.kind,item.exchange,item.sequence,_REQUEST_BODY_END)
+					elif item.kind is EventKind.RESPONSE_WRITABLE:self._signal_response_stream(item.kind,item.exchange)
+		except NativeError as error:
+			if self._stopping.is_set()or self._draining.is_set()and error.status==int(ResultCode.CLOSED):return
+			self._fail_reader(error)
+		except BaseException as error:self._fail_reader(error)
+	def _read_web_sockets(self)->None:
+		dispatcher=self._web_socket_dispatcher
+		if dispatcher is None:return
+		while not self._stopping.is_set():
+			try:
+				event=self._runtime.take_websocket(100)
+				if event is not None:dispatcher.handle(event)
+			except NativeError as error:
+				if self._stopping.is_set()or self._draining.is_set()and error.status==int(ResultCode.CLOSED):return
+				self._record(error);return
+			except BaseException as error:self._record(error);return
+	def _fail_reader(self,error:BaseException)->None:
+		self._record(error);self._finish_request_streams(RuntimeError('request event reader failed'))
+		try:self._runtime.drain()
+		except BaseException as drain_error:self._record(drain_error)
+	def _open_request_stream(self,request:Request,sequence:int)->None:
+		if request.body_delivery is not BodyDelivery.STREAM:return
+		stream=_RequestBodyReader(request,self._request_stream_capacity,sequence)
+		with self._request_stream_lock:
+			if request.exchange in self._request_streams:raise RuntimeError('request body stream is already registered')
+			self._request_streams[request.exchange]=stream
+		request._attach_body_reader(stream)
+	def _signal_request_stream(self,kind:EventKind,exchange:ExchangeId,sequence:int,item:_RequestBodyItem|None)->None:
+		with self._request_stream_lock:
+			stream=self._request_streams.get(exchange)
+			if kind in(EventKind.REQUEST_END,EventKind.REQUEST_CANCELLED,EventKind.TERMINAL):self._request_streams.pop(exchange,None)
+		if stream is None:
+			if kind not in(EventKind.REQUEST_CANCELLED,EventKind.TERMINAL):self._record(RuntimeError('request body event has no active stream'))
+			return
+		if kind in(EventKind.REQUEST_CANCELLED,EventKind.TERMINAL):detail='request body stream was cancelled'if kind is EventKind.REQUEST_CANCELLED else'request body stream reached terminal state';stream.finish(RuntimeError(detail))
+		elif item is None:self._record(RuntimeError('request body data event is empty'))
+		elif not stream.offer(sequence,item):
+			self._record(RuntimeError('request body stream rejected an event'))
+			try:self._runtime.respond(exchange,Response(status=500,body=b'internal server error'))
+			except BaseException as error:self._record(error)
+	def _finish_request_streams(self,error:BaseException)->None:
+		with self._request_stream_lock:streams=tuple(self._request_streams.values())
+		for stream in streams:stream.finish(error)
+	def _admit(self,request:Request,retained_bytes:int)->None:
+		with self._handler_lock:handler=self._handlers.get(request.handler_binding_id)
+		if handler is None:self._reject(request,RuntimeError('request has no Python handler'));return
+		with self._retention_lock:
+			if retained_bytes>self._retained_byte_capacity or self._retained_bytes>self._retained_byte_capacity-retained_bytes:overloaded=True
+			else:overloaded=False;self._retained_bytes+=retained_bytes
+		if overloaded:self._reject(request,RuntimeError('Python dispatch byte capacity is full'),503);return
+		work:_WorkItem=(handler,request,retained_bytes)
+		try:self._queue.put(work,block=False)
+		except queue.Full:
+			with self._retention_lock:self._retained_bytes-=retained_bytes
+			self._reject(request,RuntimeError('Python dispatch queue is full'),503)
+	def _reject(self,request:Request,error:BaseException,status:int=500)->None:
+		self._record(error)
+		try:detail=b'service unavailable'if status==503 else b'internal server error';self._runtime.respond(request.exchange,Response(status=status,body=detail))
+		except BaseException as submission_error:
+			if not _retired_submission(submission_error):self._record(submission_error)
+	def _run_worker(self)->None:
+		while True:
+			work=self._queue.get()
+			if work is None:return
+			try:
+				handler,request,_retained_bytes=work
+				try:
+					response=handler(request)
+					if not isinstance(response,(Response,FileResponse,StreamingResponse,ServerSentEventsResponse,WebSocketResponse)):raise TypeError('a CoAkka HTTP handler returned an unsupported response')
+				except BaseException as error:self._reject(request,error)
+				else:
+					try:
+						if isinstance(response,WebSocketResponse):
+							dispatcher=self._web_socket_dispatcher
+							if dispatcher is None:raise RuntimeError('handler returned an undeclared WebSocket response')
+							try:dispatcher.accept(request.exchange,response)
+							except BaseException as error:self._reject(request,error)
+						elif isinstance(response,FileResponse):self._runtime.respond_file(request.exchange,response)
+						elif isinstance(response,ServerSentEventsResponse):self._server_sent_events_response(request.exchange,response)
+						elif isinstance(response,StreamingResponse):self._stream_response(request.exchange,response)
+						else:self._runtime.respond(request.exchange,response)
+					except BaseException as error:
+						if not _retired_submission(error):self._record(error)
+			finally:
+				work[1].body_reader.close()
+				with self._retention_lock:self._retained_bytes-=work[2]
+	def _signal_response_stream(self,kind:EventKind,exchange:ExchangeId)->None:
+		with self._response_stream_lock:
+			state=self._response_streams.get(exchange)
+			if kind is EventKind.TERMINAL:self._response_streams.pop(exchange,None)
+		if state is None:return
+		if kind is EventKind.RESPONSE_WRITABLE:state.grant_writable()
+		elif kind is EventKind.REQUEST_CANCELLED:state.terminate(RuntimeError('response stream request was cancelled'))
+		else:state.terminate(RuntimeError('response stream reached terminal state'))
+	def _stream_response(self,exchange:ExchangeId,response:StreamingResponse)->None:
+		state=_ResponseStreamState()
+		with self._response_stream_lock:
+			if exchange in self._response_streams:raise RuntimeError('response stream is already registered')
+			self._response_streams[exchange]=state
+		try:
+			try:self._runtime.start_response_stream(exchange,Response(status=response.status,headers=response.headers))
+			except BaseException as error:
+				if _retired_submission(error):return
+				self._record(error)
+				try:self._runtime.respond(exchange,Response(status=500,body=b'internal server error'))
+				except BaseException as fallback_error:self._record(fallback_error)
+				return
+			state.await_writable(self._response_write_timeout_ms);writer=ResponseStreamWriter(self._runtime,exchange,state,self._response_write_timeout_ms)
+			try:
+				trailers=response.producer(writer)
+				if not isinstance(trailers,Headers):raise TypeError('response stream producer must return Headers')
+			except BaseException as error:self._record(error);trailers=_EMPTY_HEADERS
+			finally:writer._close()
+			try:self._finish_response_stream(exchange,trailers,state)
+			except BaseException as error:
+				if not _retired_submission(error):self._record(error)
+		finally:
+			with self._response_stream_lock:
+				if self._response_streams.get(exchange)is state:del self._response_streams[exchange]
+	def _server_sent_events_response(self,exchange:ExchangeId,response:ServerSentEventsResponse)->None:
+		state=_ResponseStreamState()
+		with self._response_stream_lock:
+			if exchange in self._response_streams:raise RuntimeError('response stream is already registered')
+			self._response_streams[exchange]=state
+		try:
+			try:self._runtime.start_sse(exchange,response.headers)
+			except BaseException as error:
+				self._record(error)
+				try:self._runtime.respond(exchange,Response(status=500,body=b'internal server error'))
+				except BaseException as fallback_error:self._record(fallback_error)
+				return
+			state.await_writable(self._response_write_timeout_ms);writer=ServerSentEventsWriter(self._runtime,exchange,state,self._response_write_timeout_ms)
+			try:response.producer(writer)
+			except BaseException as error:self._record(error)
+			finally:writer._close()
+			try:self._finish_response_stream(exchange,_EMPTY_HEADERS,state)
+			except BaseException as error:
+				if not _retired_submission(error):self._record(error)
+		finally:
+			with self._response_stream_lock:
+				if self._response_streams.get(exchange)is state:del self._response_streams[exchange]
+	def _finish_response_stream(self,exchange:ExchangeId,trailers:Headers,state:_ResponseStreamState)->None:
+		'Retry only Core-declared FINAL pressure after its recovery doorbell.'
+		while True:
+			try:self._runtime.finish_response_stream(exchange,trailers);return
+			except NativeError as error:
+				if error.status!=int(ResultCode.CAPACITY_EXHAUSTED):raise
+				state.await_writable(self._response_write_timeout_ms)
+	@staticmethod
+	def _join(thread:threading.Thread,deadline:float,owner:str)->None:
+		if not thread.is_alive():return
+		remaining=deadline-time.monotonic()
+		if remaining<=0:raise TimeoutError(f"timed out joining {owner}")
+		thread.join(remaining)
+		if thread.is_alive():raise TimeoutError(f"timed out joining {owner}")