forge-tool 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- forge_tool/__init__.py +196 -0
- forge_tool/dora.py +447 -0
- forge_tool/endpoint/__init__.py +69 -0
- forge_tool/endpoint/exceptions.py +20 -0
- forge_tool/endpoint/models.py +550 -0
- forge_tool/endpoint/protocol.py +103 -0
- forge_tool/handler.py +903 -0
- forge_tool/py.typed +0 -0
- forge_tool/wire/__init__.py +127 -0
- forge_tool/wire/codec.py +247 -0
- forge_tool/wire/descriptor.py +174 -0
- forge_tool/wire/envelope.py +281 -0
- forge_tool/wire/errors.py +14 -0
- forge_tool/wire/factories.py +443 -0
- forge_tool/wire/messages.py +571 -0
- forge_tool-0.1.0.dist-info/METADATA +443 -0
- forge_tool-0.1.0.dist-info/RECORD +19 -0
- forge_tool-0.1.0.dist-info/WHEEL +4 -0
- forge_tool-0.1.0.dist-info/licenses/LICENSE +201 -0
forge_tool/__init__.py
ADDED
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
"""Public Forge ToolEndpoint contracts and logical Wire protocol."""
|
|
2
|
+
|
|
3
|
+
from importlib.metadata import PackageNotFoundError, version
|
|
4
|
+
|
|
5
|
+
from .endpoint import (
|
|
6
|
+
ActionToolEndpoint,
|
|
7
|
+
EndpointRegistryOperation,
|
|
8
|
+
EndpointRegistryResponse,
|
|
9
|
+
EndpointRegistryResponseStatus,
|
|
10
|
+
EndpointState,
|
|
11
|
+
EndpointStatus,
|
|
12
|
+
ExecutionPhase,
|
|
13
|
+
QueryToolEndpoint,
|
|
14
|
+
SessionToolEndpoint,
|
|
15
|
+
ToolAccepted,
|
|
16
|
+
ToolContext,
|
|
17
|
+
ToolControlCommand,
|
|
18
|
+
ToolControlResponse,
|
|
19
|
+
ToolControlStatus,
|
|
20
|
+
ToolEndpointDescriptor,
|
|
21
|
+
ToolEndpointError,
|
|
22
|
+
ToolError,
|
|
23
|
+
ToolEvent,
|
|
24
|
+
ToolEventEmitter,
|
|
25
|
+
ToolEventType,
|
|
26
|
+
ToolExecutionKey,
|
|
27
|
+
ToolExecutionStatus,
|
|
28
|
+
ToolOperationDescriptor,
|
|
29
|
+
ToolRequest,
|
|
30
|
+
ToolResult,
|
|
31
|
+
ToolResultResponse,
|
|
32
|
+
ToolResultResponseStatus,
|
|
33
|
+
ToolResultStatus,
|
|
34
|
+
ToolSemantics,
|
|
35
|
+
validate_execution_result,
|
|
36
|
+
)
|
|
37
|
+
|
|
38
|
+
from .wire import (
|
|
39
|
+
DEFAULT_MAX_MESSAGE_BYTES,
|
|
40
|
+
MAX_JSON_DEPTH,
|
|
41
|
+
MAX_SAFE_JSON_INTEGER,
|
|
42
|
+
TOOL_ENDPOINT_PROTOCOL,
|
|
43
|
+
TOOL_MESSAGE_TYPES,
|
|
44
|
+
ToolEnvelope,
|
|
45
|
+
ToolMessageType,
|
|
46
|
+
ToolProtocolError,
|
|
47
|
+
control_request_from_payload,
|
|
48
|
+
control_request_to_payload,
|
|
49
|
+
control_response_from_payload,
|
|
50
|
+
control_response_to_payload,
|
|
51
|
+
decode_envelope,
|
|
52
|
+
encode_envelope,
|
|
53
|
+
endpoint_descriptor_from_payload,
|
|
54
|
+
endpoint_descriptor_to_payload,
|
|
55
|
+
endpoint_registry_response_from_payload,
|
|
56
|
+
endpoint_registry_response_to_payload,
|
|
57
|
+
endpoint_status_from_envelope,
|
|
58
|
+
endpoint_status_to_payload,
|
|
59
|
+
error_from_payload,
|
|
60
|
+
error_to_payload,
|
|
61
|
+
event_from_payload,
|
|
62
|
+
event_to_payload,
|
|
63
|
+
execution_status_from_payload,
|
|
64
|
+
execution_status_to_payload,
|
|
65
|
+
invoke_request_from_envelope,
|
|
66
|
+
invoke_request_to_payload,
|
|
67
|
+
invoke_response_from_payload,
|
|
68
|
+
invoke_response_to_payload,
|
|
69
|
+
make_control_request_envelope,
|
|
70
|
+
make_control_response_envelope,
|
|
71
|
+
make_endpoint_registry_response_envelope,
|
|
72
|
+
make_endpoint_status_envelope,
|
|
73
|
+
make_error_envelope,
|
|
74
|
+
make_error_response_envelope,
|
|
75
|
+
make_event_envelope,
|
|
76
|
+
make_invoke_request_envelope,
|
|
77
|
+
make_invoke_response_envelope,
|
|
78
|
+
make_registration_envelope,
|
|
79
|
+
make_result_request_envelope,
|
|
80
|
+
make_result_response_envelope,
|
|
81
|
+
make_status_request_envelope,
|
|
82
|
+
make_status_response_envelope,
|
|
83
|
+
make_unregister_envelope,
|
|
84
|
+
result_response_from_payload,
|
|
85
|
+
result_response_to_payload,
|
|
86
|
+
status_response_from_payload,
|
|
87
|
+
status_response_to_payload,
|
|
88
|
+
tool_context_to_payload,
|
|
89
|
+
tool_error_from_payload,
|
|
90
|
+
tool_error_to_payload,
|
|
91
|
+
tool_result_from_payload,
|
|
92
|
+
tool_result_to_payload,
|
|
93
|
+
validate_management_response_correlation,
|
|
94
|
+
validate_message_envelope,
|
|
95
|
+
validate_registration_envelope,
|
|
96
|
+
validate_response_correlation,
|
|
97
|
+
)
|
|
98
|
+
from .handler import ToolEndpointHandler
|
|
99
|
+
|
|
100
|
+
try:
|
|
101
|
+
__version__ = version("forge-tool")
|
|
102
|
+
except PackageNotFoundError:
|
|
103
|
+
__version__ = "0+unknown"
|
|
104
|
+
|
|
105
|
+
__all__ = [
|
|
106
|
+
"DEFAULT_MAX_MESSAGE_BYTES",
|
|
107
|
+
"MAX_JSON_DEPTH",
|
|
108
|
+
"MAX_SAFE_JSON_INTEGER",
|
|
109
|
+
"TOOL_ENDPOINT_PROTOCOL",
|
|
110
|
+
"TOOL_MESSAGE_TYPES",
|
|
111
|
+
"ActionToolEndpoint",
|
|
112
|
+
"EndpointRegistryOperation",
|
|
113
|
+
"EndpointRegistryResponse",
|
|
114
|
+
"EndpointRegistryResponseStatus",
|
|
115
|
+
"EndpointState",
|
|
116
|
+
"EndpointStatus",
|
|
117
|
+
"ExecutionPhase",
|
|
118
|
+
"QueryToolEndpoint",
|
|
119
|
+
"SessionToolEndpoint",
|
|
120
|
+
"ToolAccepted",
|
|
121
|
+
"ToolContext",
|
|
122
|
+
"ToolControlCommand",
|
|
123
|
+
"ToolControlResponse",
|
|
124
|
+
"ToolControlStatus",
|
|
125
|
+
"ToolEndpointDescriptor",
|
|
126
|
+
"ToolEndpointError",
|
|
127
|
+
"ToolEndpointHandler",
|
|
128
|
+
"ToolEnvelope",
|
|
129
|
+
"ToolError",
|
|
130
|
+
"ToolEvent",
|
|
131
|
+
"ToolEventEmitter",
|
|
132
|
+
"ToolEventType",
|
|
133
|
+
"ToolExecutionKey",
|
|
134
|
+
"ToolExecutionStatus",
|
|
135
|
+
"ToolMessageType",
|
|
136
|
+
"ToolOperationDescriptor",
|
|
137
|
+
"ToolProtocolError",
|
|
138
|
+
"ToolRequest",
|
|
139
|
+
"ToolResult",
|
|
140
|
+
"ToolResultResponse",
|
|
141
|
+
"ToolResultResponseStatus",
|
|
142
|
+
"ToolResultStatus",
|
|
143
|
+
"ToolSemantics",
|
|
144
|
+
"__version__",
|
|
145
|
+
"control_request_from_payload",
|
|
146
|
+
"control_request_to_payload",
|
|
147
|
+
"control_response_from_payload",
|
|
148
|
+
"control_response_to_payload",
|
|
149
|
+
"decode_envelope",
|
|
150
|
+
"encode_envelope",
|
|
151
|
+
"endpoint_descriptor_from_payload",
|
|
152
|
+
"endpoint_descriptor_to_payload",
|
|
153
|
+
"endpoint_registry_response_from_payload",
|
|
154
|
+
"endpoint_registry_response_to_payload",
|
|
155
|
+
"endpoint_status_from_envelope",
|
|
156
|
+
"endpoint_status_to_payload",
|
|
157
|
+
"error_from_payload",
|
|
158
|
+
"error_to_payload",
|
|
159
|
+
"event_from_payload",
|
|
160
|
+
"event_to_payload",
|
|
161
|
+
"execution_status_from_payload",
|
|
162
|
+
"execution_status_to_payload",
|
|
163
|
+
"invoke_request_from_envelope",
|
|
164
|
+
"invoke_request_to_payload",
|
|
165
|
+
"invoke_response_from_payload",
|
|
166
|
+
"invoke_response_to_payload",
|
|
167
|
+
"make_control_request_envelope",
|
|
168
|
+
"make_control_response_envelope",
|
|
169
|
+
"make_endpoint_registry_response_envelope",
|
|
170
|
+
"make_endpoint_status_envelope",
|
|
171
|
+
"make_error_envelope",
|
|
172
|
+
"make_error_response_envelope",
|
|
173
|
+
"make_event_envelope",
|
|
174
|
+
"make_invoke_request_envelope",
|
|
175
|
+
"make_invoke_response_envelope",
|
|
176
|
+
"make_registration_envelope",
|
|
177
|
+
"make_result_request_envelope",
|
|
178
|
+
"make_result_response_envelope",
|
|
179
|
+
"make_status_request_envelope",
|
|
180
|
+
"make_status_response_envelope",
|
|
181
|
+
"make_unregister_envelope",
|
|
182
|
+
"result_response_from_payload",
|
|
183
|
+
"result_response_to_payload",
|
|
184
|
+
"status_response_from_payload",
|
|
185
|
+
"status_response_to_payload",
|
|
186
|
+
"tool_context_to_payload",
|
|
187
|
+
"tool_error_from_payload",
|
|
188
|
+
"tool_error_to_payload",
|
|
189
|
+
"tool_result_from_payload",
|
|
190
|
+
"tool_result_to_payload",
|
|
191
|
+
"validate_execution_result",
|
|
192
|
+
"validate_management_response_correlation",
|
|
193
|
+
"validate_message_envelope",
|
|
194
|
+
"validate_registration_envelope",
|
|
195
|
+
"validate_response_correlation",
|
|
196
|
+
]
|
forge_tool/dora.py
ADDED
|
@@ -0,0 +1,447 @@
|
|
|
1
|
+
"""Optional Arrow/Dora carrier binding for an embedded ToolEndpoint handler."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import asyncio
|
|
6
|
+
import logging
|
|
7
|
+
from collections.abc import Awaitable, Callable
|
|
8
|
+
|
|
9
|
+
import pyarrow as pa
|
|
10
|
+
from forge_msgs import ToolMessage, ToolMessageSizeError
|
|
11
|
+
|
|
12
|
+
from .endpoint import ToolError
|
|
13
|
+
from .handler import ToolEndpointHandler
|
|
14
|
+
from .wire import (
|
|
15
|
+
DEFAULT_MAX_MESSAGE_BYTES,
|
|
16
|
+
ToolEnvelope,
|
|
17
|
+
ToolProtocolError,
|
|
18
|
+
make_error_response_envelope,
|
|
19
|
+
validate_message_envelope,
|
|
20
|
+
)
|
|
21
|
+
from .wire.codec import encoded_envelope_size
|
|
22
|
+
|
|
23
|
+
logger = logging.getLogger(__name__)
|
|
24
|
+
|
|
25
|
+
_CORRELATED_ERROR_RESERVE_BYTES = 512
|
|
26
|
+
_MIN_BINDING_MESSAGE_BYTES = 1_024
|
|
27
|
+
_DEFAULT_CARRIER_OVERHEAD_BYTES = 65_536
|
|
28
|
+
|
|
29
|
+
type _ToolArrowValue = pa.RecordBatch | pa.Table | pa.StructArray
|
|
30
|
+
type DoraEventSink = Callable[[pa.RecordBatch], Awaitable[None]]
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def _message_envelope(message: ToolMessage) -> ToolEnvelope:
|
|
34
|
+
return ToolEnvelope(
|
|
35
|
+
protocol=message.protocol,
|
|
36
|
+
message_type=message.message_type,
|
|
37
|
+
request_id=message.request_id,
|
|
38
|
+
invocation_id=message.invocation_id,
|
|
39
|
+
attempt_id=message.attempt_id,
|
|
40
|
+
endpoint_id=message.endpoint_id,
|
|
41
|
+
endpoint_instance_id=message.endpoint_instance_id,
|
|
42
|
+
operation=message.operation,
|
|
43
|
+
sequence=message.sequence,
|
|
44
|
+
payload=message.payload(),
|
|
45
|
+
)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def _validate_maximum(value: int, field_name: str) -> int:
|
|
49
|
+
if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
|
|
50
|
+
raise ValueError(f"{field_name} must be a positive integer")
|
|
51
|
+
return value
|
|
52
|
+
|
|
53
|
+
|
|
54
|
+
def _validate_envelope_size(envelope: ToolEnvelope, maximum: int) -> None:
|
|
55
|
+
size = encoded_envelope_size(envelope)
|
|
56
|
+
if size > maximum:
|
|
57
|
+
raise ToolProtocolError(
|
|
58
|
+
"FORGE_PROTOCOL_MESSAGE_TOO_LARGE",
|
|
59
|
+
f"message size {size} exceeds limit {maximum}",
|
|
60
|
+
)
|
|
61
|
+
|
|
62
|
+
|
|
63
|
+
def _carrier_size(value: _ToolArrowValue) -> int | None:
|
|
64
|
+
if isinstance(value, (pa.RecordBatch, pa.Table, pa.StructArray)):
|
|
65
|
+
return value.nbytes
|
|
66
|
+
return None
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def _validate_carrier_size(value: _ToolArrowValue, maximum: int) -> None:
|
|
70
|
+
size = _carrier_size(value)
|
|
71
|
+
if size is not None and size > maximum:
|
|
72
|
+
raise ToolProtocolError(
|
|
73
|
+
"FORGE_PROTOCOL_MESSAGE_TOO_LARGE",
|
|
74
|
+
f"Arrow carrier size {size} exceeds limit {maximum}",
|
|
75
|
+
)
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def _correlated_protocol_error(
|
|
79
|
+
error: ToolProtocolError,
|
|
80
|
+
request: ToolEnvelope,
|
|
81
|
+
*,
|
|
82
|
+
max_message_bytes: int,
|
|
83
|
+
max_request_bytes: int | None = None,
|
|
84
|
+
) -> ToolEnvelope:
|
|
85
|
+
details: dict[str, object] = {}
|
|
86
|
+
if error.code == "FORGE_PROTOCOL_MESSAGE_TOO_LARGE":
|
|
87
|
+
message = "ToolEndpoint message exceeds the configured size limit"
|
|
88
|
+
details["max_message_bytes"] = max_message_bytes
|
|
89
|
+
if max_request_bytes is not None:
|
|
90
|
+
details["max_request_bytes"] = max_request_bytes
|
|
91
|
+
else:
|
|
92
|
+
message = "ToolEndpoint response violates the Wire protocol"
|
|
93
|
+
return make_error_response_envelope(
|
|
94
|
+
ToolError(
|
|
95
|
+
code=error.code,
|
|
96
|
+
message=message,
|
|
97
|
+
retryable=False,
|
|
98
|
+
details=details,
|
|
99
|
+
),
|
|
100
|
+
request,
|
|
101
|
+
)
|
|
102
|
+
|
|
103
|
+
|
|
104
|
+
def _correlated_internal_error(request: ToolEnvelope) -> ToolEnvelope:
|
|
105
|
+
return make_error_response_envelope(
|
|
106
|
+
ToolError(
|
|
107
|
+
code="FORGE_ENDPOINT_INTERNAL",
|
|
108
|
+
message="endpoint failed to produce a valid response",
|
|
109
|
+
retryable=False,
|
|
110
|
+
),
|
|
111
|
+
request,
|
|
112
|
+
)
|
|
113
|
+
|
|
114
|
+
|
|
115
|
+
def tool_message_to_envelope(
|
|
116
|
+
message: ToolMessage,
|
|
117
|
+
*,
|
|
118
|
+
max_message_bytes: int = DEFAULT_MAX_MESSAGE_BYTES,
|
|
119
|
+
) -> ToolEnvelope:
|
|
120
|
+
"""Convert one carrier model and enforce the logical encoded-message limit."""
|
|
121
|
+
if not isinstance(message, ToolMessage):
|
|
122
|
+
raise TypeError("message must be a forge_msgs.ToolMessage")
|
|
123
|
+
maximum = _validate_maximum(max_message_bytes, "max_message_bytes")
|
|
124
|
+
envelope = _message_envelope(message)
|
|
125
|
+
_validate_envelope_size(envelope, maximum)
|
|
126
|
+
return envelope
|
|
127
|
+
|
|
128
|
+
|
|
129
|
+
def tool_envelope_to_message(
|
|
130
|
+
envelope: ToolEnvelope,
|
|
131
|
+
*,
|
|
132
|
+
max_message_bytes: int = DEFAULT_MAX_MESSAGE_BYTES,
|
|
133
|
+
) -> ToolMessage:
|
|
134
|
+
"""Convert one logical envelope and enforce the logical encoded-message limit."""
|
|
135
|
+
if not isinstance(envelope, ToolEnvelope):
|
|
136
|
+
raise TypeError("envelope must be a ToolEnvelope")
|
|
137
|
+
maximum = _validate_maximum(max_message_bytes, "max_message_bytes")
|
|
138
|
+
validate_message_envelope(envelope)
|
|
139
|
+
_validate_envelope_size(envelope, maximum)
|
|
140
|
+
return ToolMessage.from_payload(
|
|
141
|
+
message_type=envelope.message_type,
|
|
142
|
+
request_id=envelope.request_id,
|
|
143
|
+
invocation_id=envelope.invocation_id,
|
|
144
|
+
attempt_id=envelope.attempt_id,
|
|
145
|
+
endpoint_id=envelope.endpoint_id,
|
|
146
|
+
endpoint_instance_id=envelope.endpoint_instance_id,
|
|
147
|
+
operation=envelope.operation,
|
|
148
|
+
sequence=envelope.sequence,
|
|
149
|
+
payload=envelope.payload,
|
|
150
|
+
)
|
|
151
|
+
|
|
152
|
+
|
|
153
|
+
class DoraToolEndpointBinding:
|
|
154
|
+
"""Bridge bounded Dora ToolMessage inputs to a logical endpoint handler.
|
|
155
|
+
|
|
156
|
+
The binding owns no Dora ``Node`` and does not observe or rewrite Dora event
|
|
157
|
+
metadata. A business node remains responsible for receiving the input, awaiting
|
|
158
|
+
``handle_input``, and publishing the returned RecordBatch on its configured output.
|
|
159
|
+
Raw in-memory Arrow carriers and payload JSON are bounded before typed JSON handling.
|
|
160
|
+
IPC bytes are rejected because compressed IPC must be decoded by an upstream transport
|
|
161
|
+
with its own framing and decompression limits. Accepted requests reserve response
|
|
162
|
+
headroom so endpoint and encoding failures can remain correlated within the configured
|
|
163
|
+
logical encoded-message limit.
|
|
164
|
+
"""
|
|
165
|
+
|
|
166
|
+
__slots__ = (
|
|
167
|
+
"_handler",
|
|
168
|
+
"_event_sink",
|
|
169
|
+
"_max_carrier_bytes",
|
|
170
|
+
"_max_message_bytes",
|
|
171
|
+
"_max_request_bytes",
|
|
172
|
+
)
|
|
173
|
+
|
|
174
|
+
def __init__(
|
|
175
|
+
self,
|
|
176
|
+
handler: ToolEndpointHandler,
|
|
177
|
+
*,
|
|
178
|
+
max_message_bytes: int = DEFAULT_MAX_MESSAGE_BYTES,
|
|
179
|
+
max_carrier_bytes: int | None = None,
|
|
180
|
+
event_sink: DoraEventSink | None = None,
|
|
181
|
+
) -> None:
|
|
182
|
+
if not isinstance(handler, ToolEndpointHandler):
|
|
183
|
+
raise TypeError("handler must be a ToolEndpointHandler")
|
|
184
|
+
maximum = _validate_maximum(max_message_bytes, "max_message_bytes")
|
|
185
|
+
if maximum < _MIN_BINDING_MESSAGE_BYTES:
|
|
186
|
+
raise ValueError(
|
|
187
|
+
f"max_message_bytes must be at least {_MIN_BINDING_MESSAGE_BYTES} "
|
|
188
|
+
"for correlated error responses"
|
|
189
|
+
)
|
|
190
|
+
carrier_maximum = (
|
|
191
|
+
maximum + _DEFAULT_CARRIER_OVERHEAD_BYTES
|
|
192
|
+
if max_carrier_bytes is None
|
|
193
|
+
else _validate_maximum(max_carrier_bytes, "max_carrier_bytes")
|
|
194
|
+
)
|
|
195
|
+
if carrier_maximum < maximum:
|
|
196
|
+
raise ValueError("max_carrier_bytes must be at least max_message_bytes")
|
|
197
|
+
if event_sink is not None and not callable(event_sink):
|
|
198
|
+
raise TypeError("event_sink must be an async callable or None")
|
|
199
|
+
|
|
200
|
+
self._handler = handler
|
|
201
|
+
self._event_sink = event_sink
|
|
202
|
+
self._max_message_bytes = maximum
|
|
203
|
+
self._max_request_bytes = maximum - _CORRELATED_ERROR_RESERVE_BYTES
|
|
204
|
+
self._max_carrier_bytes = carrier_maximum
|
|
205
|
+
|
|
206
|
+
@property
|
|
207
|
+
def handler(self) -> ToolEndpointHandler:
|
|
208
|
+
"""Return the embedded transport-independent handler."""
|
|
209
|
+
return self._handler
|
|
210
|
+
|
|
211
|
+
@property
|
|
212
|
+
def max_message_bytes(self) -> int:
|
|
213
|
+
"""Return the outbound logical encoded-message limit."""
|
|
214
|
+
return self._max_message_bytes
|
|
215
|
+
|
|
216
|
+
@property
|
|
217
|
+
def max_request_bytes(self) -> int:
|
|
218
|
+
"""Return the inbound execution limit after correlated-error headroom."""
|
|
219
|
+
return self._max_request_bytes
|
|
220
|
+
|
|
221
|
+
@property
|
|
222
|
+
def max_carrier_bytes(self) -> int:
|
|
223
|
+
"""Return the pre-decode Arrow carrier byte limit."""
|
|
224
|
+
return self._max_carrier_bytes
|
|
225
|
+
|
|
226
|
+
def _fallback_to_arrow(
|
|
227
|
+
self,
|
|
228
|
+
fallback: ToolEnvelope,
|
|
229
|
+
request: ToolEnvelope,
|
|
230
|
+
original_error: Exception,
|
|
231
|
+
) -> pa.RecordBatch:
|
|
232
|
+
try:
|
|
233
|
+
return tool_envelope_to_message(
|
|
234
|
+
fallback,
|
|
235
|
+
max_message_bytes=self._max_message_bytes,
|
|
236
|
+
).to_arrow()
|
|
237
|
+
except Exception:
|
|
238
|
+
logger.exception(
|
|
239
|
+
"correlated ToolEndpoint fallback does not fit request_id=%s "
|
|
240
|
+
"invocation_id=%s attempt_id=%s endpoint_id=%s "
|
|
241
|
+
"endpoint_instance_id=%s operation=%s",
|
|
242
|
+
request.request_id,
|
|
243
|
+
request.invocation_id,
|
|
244
|
+
request.attempt_id,
|
|
245
|
+
request.endpoint_id,
|
|
246
|
+
request.endpoint_instance_id,
|
|
247
|
+
request.operation,
|
|
248
|
+
)
|
|
249
|
+
raise original_error
|
|
250
|
+
|
|
251
|
+
def _response_to_arrow(
|
|
252
|
+
self,
|
|
253
|
+
response: ToolEnvelope,
|
|
254
|
+
request: ToolEnvelope,
|
|
255
|
+
) -> pa.RecordBatch:
|
|
256
|
+
try:
|
|
257
|
+
return tool_envelope_to_message(
|
|
258
|
+
response,
|
|
259
|
+
max_message_bytes=self._max_message_bytes,
|
|
260
|
+
).to_arrow()
|
|
261
|
+
except ToolProtocolError as error:
|
|
262
|
+
fallback = _correlated_protocol_error(
|
|
263
|
+
error,
|
|
264
|
+
request,
|
|
265
|
+
max_message_bytes=self._max_message_bytes,
|
|
266
|
+
)
|
|
267
|
+
return self._fallback_to_arrow(fallback, request, error)
|
|
268
|
+
except (TypeError, ValueError, UnicodeError) as error:
|
|
269
|
+
return self._fallback_to_arrow(
|
|
270
|
+
_correlated_internal_error(request),
|
|
271
|
+
request,
|
|
272
|
+
error,
|
|
273
|
+
)
|
|
274
|
+
|
|
275
|
+
def _event_to_arrow(self, event: ToolEnvelope) -> pa.RecordBatch:
|
|
276
|
+
"""Encode one event without fabricating a correlated response on failure."""
|
|
277
|
+
if event.message_type != "tool.event":
|
|
278
|
+
raise ValueError("event sink only accepts tool.event envelopes")
|
|
279
|
+
return tool_envelope_to_message(
|
|
280
|
+
event,
|
|
281
|
+
max_message_bytes=self._max_message_bytes,
|
|
282
|
+
).to_arrow()
|
|
283
|
+
|
|
284
|
+
def _request_from_arrow(self, value: _ToolArrowValue) -> ToolEnvelope:
|
|
285
|
+
if isinstance(value, bytes):
|
|
286
|
+
raise TypeError(
|
|
287
|
+
"DoraToolEndpointBinding does not accept IPC bytes; decode them upstream "
|
|
288
|
+
"under bounded framing and decompression limits"
|
|
289
|
+
)
|
|
290
|
+
_validate_carrier_size(value, self._max_carrier_bytes)
|
|
291
|
+
try:
|
|
292
|
+
message = ToolMessage.from_arrow(
|
|
293
|
+
value,
|
|
294
|
+
max_payload_json_bytes=self._max_message_bytes,
|
|
295
|
+
)
|
|
296
|
+
except ToolMessageSizeError as error:
|
|
297
|
+
raise ToolProtocolError(
|
|
298
|
+
"FORGE_PROTOCOL_MESSAGE_TOO_LARGE",
|
|
299
|
+
str(error),
|
|
300
|
+
) from error
|
|
301
|
+
request = _message_envelope(message)
|
|
302
|
+
|
|
303
|
+
# Do not answer a request for another endpoint route. Once the route is trusted,
|
|
304
|
+
# accepted requests reserve enough headroom for later correlated failures.
|
|
305
|
+
self._handler.validate_request_route(request)
|
|
306
|
+
return request
|
|
307
|
+
|
|
308
|
+
async def dispatch_input(
|
|
309
|
+
self,
|
|
310
|
+
value: _ToolArrowValue,
|
|
311
|
+
) -> tuple[pa.RecordBatch, ...]:
|
|
312
|
+
"""Dispatch one execution request.
|
|
313
|
+
|
|
314
|
+
Action invoke requires ``event_sink``. The binding publishes its response and
|
|
315
|
+
buffered events through that same sink, awaiting the response publication before
|
|
316
|
+
opening the late-event barrier, and returns an empty tuple. Other request types
|
|
317
|
+
retain the response-first returned-tuple API.
|
|
318
|
+
"""
|
|
319
|
+
request = self._request_from_arrow(value)
|
|
320
|
+
try:
|
|
321
|
+
_validate_envelope_size(request, self._max_request_bytes)
|
|
322
|
+
except ToolProtocolError as error:
|
|
323
|
+
fallback = _correlated_protocol_error(
|
|
324
|
+
error,
|
|
325
|
+
request,
|
|
326
|
+
max_message_bytes=self._max_message_bytes,
|
|
327
|
+
max_request_bytes=self._max_request_bytes,
|
|
328
|
+
)
|
|
329
|
+
return (self._fallback_to_arrow(fallback, request, error),)
|
|
330
|
+
|
|
331
|
+
operation_descriptor = next(
|
|
332
|
+
operation
|
|
333
|
+
for operation in self._handler.descriptor.operations
|
|
334
|
+
if operation.name == request.operation
|
|
335
|
+
)
|
|
336
|
+
action_invoke = (
|
|
337
|
+
request.message_type == "tool.invoke.request"
|
|
338
|
+
and operation_descriptor.semantics == "action"
|
|
339
|
+
)
|
|
340
|
+
if action_invoke and self._event_sink is None:
|
|
341
|
+
raise RuntimeError(
|
|
342
|
+
"Action dispatch requires an asynchronous event_sink publisher"
|
|
343
|
+
)
|
|
344
|
+
|
|
345
|
+
publish_ready = asyncio.Event()
|
|
346
|
+
publish_failure: list[BaseException] = []
|
|
347
|
+
publish_lock = asyncio.Lock()
|
|
348
|
+
|
|
349
|
+
async def emit_event(event: ToolEnvelope) -> None:
|
|
350
|
+
await publish_ready.wait()
|
|
351
|
+
if publish_failure:
|
|
352
|
+
raise RuntimeError(
|
|
353
|
+
"Action response publication failed; event was not published"
|
|
354
|
+
) from publish_failure[0]
|
|
355
|
+
if self._event_sink is None:
|
|
356
|
+
raise RuntimeError("Action event publisher is unavailable")
|
|
357
|
+
async with publish_lock:
|
|
358
|
+
await self._event_sink(self._event_to_arrow(event))
|
|
359
|
+
|
|
360
|
+
try:
|
|
361
|
+
messages = await self._handler.dispatch(
|
|
362
|
+
request,
|
|
363
|
+
event_sink=emit_event if action_invoke else None,
|
|
364
|
+
)
|
|
365
|
+
except Exception: # noqa: BLE001 - trusted requests must receive a response.
|
|
366
|
+
logger.exception(
|
|
367
|
+
"ToolEndpoint failed request_id=%s invocation_id=%s attempt_id=%s "
|
|
368
|
+
"endpoint_id=%s endpoint_instance_id=%s operation=%s",
|
|
369
|
+
request.request_id,
|
|
370
|
+
request.invocation_id,
|
|
371
|
+
request.attempt_id,
|
|
372
|
+
request.endpoint_id,
|
|
373
|
+
request.endpoint_instance_id,
|
|
374
|
+
request.operation,
|
|
375
|
+
)
|
|
376
|
+
messages = (_correlated_internal_error(request),)
|
|
377
|
+
if not action_invoke:
|
|
378
|
+
return tuple(
|
|
379
|
+
self._event_to_arrow(message)
|
|
380
|
+
if message.message_type == "tool.event"
|
|
381
|
+
else self._response_to_arrow(message, request)
|
|
382
|
+
for message in messages
|
|
383
|
+
)
|
|
384
|
+
|
|
385
|
+
if self._event_sink is None:
|
|
386
|
+
raise RuntimeError("Action event publisher is unavailable")
|
|
387
|
+
response_batch = self._response_to_arrow(messages[0], request)
|
|
388
|
+
try:
|
|
389
|
+
async with publish_lock:
|
|
390
|
+
await self._event_sink(response_batch)
|
|
391
|
+
publish_ready.set()
|
|
392
|
+
for message in messages[1:]:
|
|
393
|
+
await self._event_sink(self._event_to_arrow(message))
|
|
394
|
+
except BaseException as error:
|
|
395
|
+
if not publish_ready.is_set():
|
|
396
|
+
publish_failure.append(error)
|
|
397
|
+
publish_ready.set()
|
|
398
|
+
raise
|
|
399
|
+
return ()
|
|
400
|
+
|
|
401
|
+
async def handle_input(self, value: _ToolArrowValue) -> pa.RecordBatch:
|
|
402
|
+
"""Handle one legacy Query input and return its single Arrow response."""
|
|
403
|
+
request = self._request_from_arrow(value)
|
|
404
|
+
self._handler.validate_invoke_route(request)
|
|
405
|
+
operation_descriptor = next(
|
|
406
|
+
operation
|
|
407
|
+
for operation in self._handler.descriptor.operations
|
|
408
|
+
if operation.name == request.operation
|
|
409
|
+
)
|
|
410
|
+
if operation_descriptor.semantics != "query":
|
|
411
|
+
raise NotImplementedError(
|
|
412
|
+
"handle_input is Query-only; Action operations must use dispatch_input"
|
|
413
|
+
)
|
|
414
|
+
try:
|
|
415
|
+
_validate_envelope_size(request, self._max_request_bytes)
|
|
416
|
+
except ToolProtocolError as error:
|
|
417
|
+
fallback = _correlated_protocol_error(
|
|
418
|
+
error,
|
|
419
|
+
request,
|
|
420
|
+
max_message_bytes=self._max_message_bytes,
|
|
421
|
+
max_request_bytes=self._max_request_bytes,
|
|
422
|
+
)
|
|
423
|
+
return self._fallback_to_arrow(fallback, request, error)
|
|
424
|
+
|
|
425
|
+
try:
|
|
426
|
+
response = await self._handler.handle_invoke(request)
|
|
427
|
+
except Exception: # noqa: BLE001 - trusted requests must receive a response.
|
|
428
|
+
logger.exception(
|
|
429
|
+
"ToolEndpoint failed request_id=%s invocation_id=%s attempt_id=%s "
|
|
430
|
+
"endpoint_id=%s endpoint_instance_id=%s operation=%s",
|
|
431
|
+
request.request_id,
|
|
432
|
+
request.invocation_id,
|
|
433
|
+
request.attempt_id,
|
|
434
|
+
request.endpoint_id,
|
|
435
|
+
request.endpoint_instance_id,
|
|
436
|
+
request.operation,
|
|
437
|
+
)
|
|
438
|
+
response = _correlated_internal_error(request)
|
|
439
|
+
return self._response_to_arrow(response, request)
|
|
440
|
+
|
|
441
|
+
|
|
442
|
+
__all__ = [
|
|
443
|
+
"DoraEventSink",
|
|
444
|
+
"DoraToolEndpointBinding",
|
|
445
|
+
"tool_envelope_to_message",
|
|
446
|
+
"tool_message_to_envelope",
|
|
447
|
+
]
|