flo-python 0.1.2__py3-none-any.whl → 0.1.4__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.
- flo/__init__.py +29 -3
- flo/actions.py +65 -12
- flo/client.py +13 -6
- flo/exceptions.py +37 -2
- flo/kv.py +74 -34
- flo/kv_body.py +116 -44
- flo/kv_txn.py +2 -1
- flo/processing.py +91 -60
- flo/retry.py +25 -3
- flo/streams.py +33 -8
- flo/types.py +194 -26
- flo/wire.py +46 -33
- flo/worker.py +606 -226
- flo/workflows.py +173 -24
- {flo_python-0.1.2.dist-info → flo_python-0.1.4.dist-info}/METADATA +108 -22
- flo_python-0.1.4.dist-info/RECORD +19 -0
- {flo_python-0.1.2.dist-info → flo_python-0.1.4.dist-info}/WHEEL +1 -1
- flo_python-0.1.2.dist-info/RECORD +0 -19
- {flo_python-0.1.2.dist-info → flo_python-0.1.4.dist-info}/licenses/LICENSE +0 -0
flo/__init__.py
CHANGED
|
@@ -46,15 +46,18 @@ from .exceptions import (
|
|
|
46
46
|
InvalidMagicError,
|
|
47
47
|
KeyTooLargeError,
|
|
48
48
|
NamespaceTooLargeError,
|
|
49
|
+
NoNamespaceError,
|
|
49
50
|
NonRetryableError,
|
|
50
51
|
NotConnectedError,
|
|
51
52
|
NotFoundError,
|
|
53
|
+
OutcomePendingError,
|
|
52
54
|
OverloadedError,
|
|
53
55
|
PayloadTooLargeError,
|
|
54
56
|
ProtocolError,
|
|
55
57
|
RateLimitedError,
|
|
56
58
|
RequestTimeoutError,
|
|
57
59
|
ServerError,
|
|
60
|
+
StaleNotFoundError,
|
|
58
61
|
TableMismatchError,
|
|
59
62
|
UnauthorizedError,
|
|
60
63
|
UnavailableError,
|
|
@@ -69,7 +72,6 @@ from .retry import DEFAULT_RETRY_POLICY, RetryPolicy
|
|
|
69
72
|
from .types import (
|
|
70
73
|
AckOptions,
|
|
71
74
|
ActionDeleteOptions,
|
|
72
|
-
ActionInfo,
|
|
73
75
|
ActionInvokeOptions,
|
|
74
76
|
ActionInvokeResult,
|
|
75
77
|
ActionListOptions,
|
|
@@ -85,10 +87,12 @@ from .types import (
|
|
|
85
87
|
DlqListOptions,
|
|
86
88
|
DlqRequeueOptions,
|
|
87
89
|
EnqueueOptions,
|
|
90
|
+
ExistsResult,
|
|
88
91
|
GetJsonResult,
|
|
89
92
|
GetOptions,
|
|
90
93
|
GetResult,
|
|
91
94
|
HistoryOptions,
|
|
95
|
+
HistoryResult,
|
|
92
96
|
IncrResult,
|
|
93
97
|
KVBeginResult,
|
|
94
98
|
KVCommitResult,
|
|
@@ -107,12 +111,14 @@ from .types import (
|
|
|
107
111
|
ProcessingCancelOptions,
|
|
108
112
|
ProcessingListEntry,
|
|
109
113
|
ProcessingListOptions,
|
|
114
|
+
ProcessingListResult,
|
|
110
115
|
ProcessingStatusOptions,
|
|
111
116
|
ProcessingStatusResult,
|
|
112
117
|
ProcessingStopOptions,
|
|
113
118
|
ProcessingSubmitOptions,
|
|
114
119
|
ProcessingSyncOptions,
|
|
115
120
|
ProcessingSyncResult,
|
|
121
|
+
ProcessKind,
|
|
116
122
|
PutOptions,
|
|
117
123
|
PutResult,
|
|
118
124
|
Ran,
|
|
@@ -125,6 +131,7 @@ from .types import (
|
|
|
125
131
|
StreamAppendOptions,
|
|
126
132
|
StreamAppendResult,
|
|
127
133
|
StreamClaimResult,
|
|
134
|
+
StreamDeleteOptions,
|
|
128
135
|
StreamGroupAckOptions,
|
|
129
136
|
StreamGroupJoinOptions,
|
|
130
137
|
StreamGroupNackOptions,
|
|
@@ -143,22 +150,28 @@ from .types import (
|
|
|
143
150
|
WorkerAwaitOptions,
|
|
144
151
|
WorkerAwaitResult,
|
|
145
152
|
WorkerCompleteOptions,
|
|
153
|
+
WorkerDetails,
|
|
146
154
|
WorkerFailOptions,
|
|
147
155
|
WorkerInfo,
|
|
148
156
|
WorkerListOptions,
|
|
149
157
|
WorkerListResult,
|
|
158
|
+
WorkerProcess,
|
|
150
159
|
WorkerRegisterOptions,
|
|
151
160
|
WorkerStatus,
|
|
152
161
|
WorkerTouchOptions,
|
|
153
162
|
WorkerType,
|
|
154
163
|
WorkflowCancelOptions,
|
|
155
164
|
WorkflowCreateOptions,
|
|
165
|
+
WorkflowDefinitionEntry,
|
|
156
166
|
WorkflowDisableOptions,
|
|
157
167
|
WorkflowEnableOptions,
|
|
158
168
|
WorkflowGetDefinitionOptions,
|
|
159
169
|
WorkflowHistoryOptions,
|
|
160
170
|
WorkflowListDefinitionsOptions,
|
|
171
|
+
WorkflowListDefinitionsResult,
|
|
161
172
|
WorkflowListRunsOptions,
|
|
173
|
+
WorkflowListRunsResult,
|
|
174
|
+
WorkflowRunEntry,
|
|
162
175
|
WorkflowSignalOptions,
|
|
163
176
|
WorkflowStartOptions,
|
|
164
177
|
WorkflowStatusOptions,
|
|
@@ -177,7 +190,7 @@ from .worker import (
|
|
|
177
190
|
)
|
|
178
191
|
from .workflows import WorkflowOperations
|
|
179
192
|
|
|
180
|
-
__version__ = "0.1.
|
|
193
|
+
__version__ = "0.1.4"
|
|
181
194
|
|
|
182
195
|
__all__ = [
|
|
183
196
|
"Transaction",
|
|
@@ -191,6 +204,8 @@ __all__ = [
|
|
|
191
204
|
"KVMGetOptions",
|
|
192
205
|
"KVExpireOptions",
|
|
193
206
|
"GetResult",
|
|
207
|
+
"HistoryResult",
|
|
208
|
+
"ExistsResult",
|
|
194
209
|
"GetJsonResult",
|
|
195
210
|
"MGetEntry",
|
|
196
211
|
"PutResult",
|
|
@@ -231,10 +246,13 @@ __all__ = [
|
|
|
231
246
|
"BlockTooLongError",
|
|
232
247
|
"ServerError",
|
|
233
248
|
"NotFoundError",
|
|
249
|
+
"NoNamespaceError",
|
|
234
250
|
"BadRequestError",
|
|
235
251
|
"ConflictError",
|
|
236
252
|
"UnauthorizedError",
|
|
237
253
|
"OverloadedError",
|
|
254
|
+
"OutcomePendingError",
|
|
255
|
+
"StaleNotFoundError",
|
|
238
256
|
"UnavailableError",
|
|
239
257
|
"RateLimitedError",
|
|
240
258
|
"InternalServerError",
|
|
@@ -281,6 +299,7 @@ __all__ = [
|
|
|
281
299
|
"StreamTrimOptions",
|
|
282
300
|
"StreamTrimResult",
|
|
283
301
|
"StreamInfoOptions",
|
|
302
|
+
"StreamDeleteOptions",
|
|
284
303
|
"StreamGroupJoinOptions",
|
|
285
304
|
"StreamGroupReadOptions",
|
|
286
305
|
"StreamGroupAckOptions",
|
|
@@ -288,7 +307,6 @@ __all__ = [
|
|
|
288
307
|
# Action types
|
|
289
308
|
"ActionType",
|
|
290
309
|
"RunStatus",
|
|
291
|
-
"ActionInfo",
|
|
292
310
|
"ActionRunStatus",
|
|
293
311
|
"ActionInvokeResult",
|
|
294
312
|
"ActionListResult",
|
|
@@ -301,7 +319,10 @@ __all__ = [
|
|
|
301
319
|
# Worker types
|
|
302
320
|
"TaskAssignment",
|
|
303
321
|
"WorkerAwaitResult",
|
|
322
|
+
"ProcessKind",
|
|
323
|
+
"WorkerDetails",
|
|
304
324
|
"WorkerInfo",
|
|
325
|
+
"WorkerProcess",
|
|
305
326
|
"WorkerListResult",
|
|
306
327
|
"WorkerStatus",
|
|
307
328
|
"WorkerType",
|
|
@@ -322,7 +343,11 @@ __all__ = [
|
|
|
322
343
|
"WorkflowCancelOptions",
|
|
323
344
|
"WorkflowHistoryOptions",
|
|
324
345
|
"WorkflowListRunsOptions",
|
|
346
|
+
"WorkflowListRunsResult",
|
|
347
|
+
"WorkflowRunEntry",
|
|
325
348
|
"WorkflowListDefinitionsOptions",
|
|
349
|
+
"WorkflowListDefinitionsResult",
|
|
350
|
+
"WorkflowDefinitionEntry",
|
|
326
351
|
"WorkflowDisableOptions",
|
|
327
352
|
"WorkflowEnableOptions",
|
|
328
353
|
"WorkflowSyncOptions",
|
|
@@ -337,5 +362,6 @@ __all__ = [
|
|
|
337
362
|
"ProcessingSyncOptions",
|
|
338
363
|
"ProcessingStatusResult",
|
|
339
364
|
"ProcessingListEntry",
|
|
365
|
+
"ProcessingListResult",
|
|
340
366
|
"ProcessingSyncResult",
|
|
341
367
|
]
|
flo/actions.py
CHANGED
|
@@ -11,7 +11,9 @@ from typing import TYPE_CHECKING
|
|
|
11
11
|
|
|
12
12
|
from .kv_body import (
|
|
13
13
|
decode_action_invoke_answer,
|
|
14
|
+
decode_action_list_answer,
|
|
14
15
|
decode_action_status_answer,
|
|
16
|
+
decode_worker_info_answer,
|
|
15
17
|
decode_worker_list_answer,
|
|
16
18
|
encode_worker_list_body,
|
|
17
19
|
)
|
|
@@ -30,10 +32,12 @@ from .types import (
|
|
|
30
32
|
WorkerAwaitOptions,
|
|
31
33
|
WorkerAwaitResult,
|
|
32
34
|
WorkerCompleteOptions,
|
|
35
|
+
WorkerDetails,
|
|
33
36
|
WorkerFailOptions,
|
|
34
37
|
WorkerListOptions,
|
|
35
38
|
WorkerListResult,
|
|
36
39
|
WorkerRegisterOptions,
|
|
40
|
+
WorkerStatus,
|
|
37
41
|
WorkerTouchOptions,
|
|
38
42
|
)
|
|
39
43
|
from .wire import (
|
|
@@ -156,28 +160,28 @@ class ActionOperations:
|
|
|
156
160
|
self,
|
|
157
161
|
options: ActionListOptions | None = None,
|
|
158
162
|
) -> ActionListResult:
|
|
159
|
-
"""List registered actions.
|
|
163
|
+
"""List a page of the namespace's registered actions.
|
|
160
164
|
|
|
161
165
|
Args:
|
|
162
|
-
options:
|
|
166
|
+
options: The page's limit and cursor (the last page's ``cursor``;
|
|
167
|
+
None starts).
|
|
163
168
|
|
|
164
169
|
Returns:
|
|
165
|
-
ActionListResult with
|
|
170
|
+
ActionListResult with the page's action names and the next
|
|
171
|
+
page's cursor, None on the last page.
|
|
166
172
|
"""
|
|
167
173
|
opts = options or ActionListOptions()
|
|
168
174
|
namespace = self._client.get_namespace(opts.namespace)
|
|
169
175
|
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
await self._client._send_and_check(
|
|
176
|
+
response = await self._client._send_and_check(
|
|
173
177
|
OpCode.ACTION_LIST,
|
|
174
178
|
namespace,
|
|
175
179
|
(opts.prefix or "").encode("utf-8"),
|
|
176
|
-
|
|
180
|
+
serialize_action_list_value(limit=opts.limit, cursor=opts.cursor),
|
|
177
181
|
)
|
|
178
182
|
|
|
179
|
-
|
|
180
|
-
return ActionListResult(
|
|
183
|
+
names, cursor = decode_action_list_answer(response.data)
|
|
184
|
+
return ActionListResult(names=names, cursor=cursor)
|
|
181
185
|
|
|
182
186
|
async def delete(
|
|
183
187
|
self,
|
|
@@ -229,6 +233,7 @@ class WorkerOperations:
|
|
|
229
233
|
|
|
230
234
|
value = serialize_worker_register_value(
|
|
231
235
|
task_types,
|
|
236
|
+
worker_type=int(opts.worker_type),
|
|
232
237
|
max_concurrency=opts.concurrency,
|
|
233
238
|
metadata=opts.metadata,
|
|
234
239
|
machine_id=opts.machine_id,
|
|
@@ -246,24 +251,57 @@ class WorkerOperations:
|
|
|
246
251
|
worker_id: str,
|
|
247
252
|
current_load: int = 0,
|
|
248
253
|
namespace: str | None = None,
|
|
249
|
-
) ->
|
|
254
|
+
) -> WorkerStatus:
|
|
250
255
|
"""Send a worker heartbeat to keep the registration alive.
|
|
251
256
|
|
|
252
257
|
Args:
|
|
253
258
|
worker_id: Worker identifier.
|
|
254
259
|
current_load: Current number of active tasks.
|
|
255
260
|
namespace: Optional namespace override.
|
|
261
|
+
|
|
262
|
+
Returns:
|
|
263
|
+
The worker's status on the server: DRAINING once it is drained.
|
|
264
|
+
|
|
265
|
+
Raises:
|
|
266
|
+
NotFoundError: The server doesn't know the worker (it never
|
|
267
|
+
registered, or was removed after going silent).
|
|
256
268
|
"""
|
|
257
269
|
import struct
|
|
258
270
|
|
|
259
271
|
ns = self._client.get_namespace(namespace)
|
|
260
272
|
value = struct.pack("<I", current_load)
|
|
261
|
-
await self._client._send_and_check(
|
|
273
|
+
response = await self._client._send_and_check(
|
|
262
274
|
OpCode.WORKER_HEARTBEAT,
|
|
263
275
|
ns,
|
|
264
276
|
worker_id.encode("utf-8"),
|
|
265
277
|
value,
|
|
266
278
|
)
|
|
279
|
+
if len(response.data) != 1:
|
|
280
|
+
raise ValueError(f"heartbeat answer is {len(response.data)} bytes, want 1")
|
|
281
|
+
return WorkerStatus(response.data[0])
|
|
282
|
+
|
|
283
|
+
async def drain(self, worker_id: str, namespace: str | None = None) -> None:
|
|
284
|
+
"""Mark a worker draining: the server gives it no more work, and
|
|
285
|
+
its heartbeats answer DRAINING until it deregisters.
|
|
286
|
+
|
|
287
|
+
Raises:
|
|
288
|
+
NotFoundError: The server doesn't know the worker.
|
|
289
|
+
"""
|
|
290
|
+
await self._client._send_and_check(
|
|
291
|
+
OpCode.WORKER_DRAIN,
|
|
292
|
+
self._client.get_namespace(namespace),
|
|
293
|
+
worker_id.encode("utf-8"),
|
|
294
|
+
b"",
|
|
295
|
+
)
|
|
296
|
+
|
|
297
|
+
async def deregister(self, worker_id: str, namespace: str | None = None) -> None:
|
|
298
|
+
"""Remove a worker from the registry."""
|
|
299
|
+
await self._client._send_and_check(
|
|
300
|
+
OpCode.WORKER_DEREGISTER,
|
|
301
|
+
self._client.get_namespace(namespace),
|
|
302
|
+
worker_id.encode("utf-8"),
|
|
303
|
+
b"",
|
|
304
|
+
)
|
|
267
305
|
|
|
268
306
|
async def await_task(
|
|
269
307
|
self,
|
|
@@ -412,8 +450,23 @@ class WorkerOperations:
|
|
|
412
450
|
OpCode.WORKER_LIST,
|
|
413
451
|
namespace,
|
|
414
452
|
b"",
|
|
415
|
-
encode_worker_list_body(opts.limit, opts.cursor),
|
|
453
|
+
encode_worker_list_body(opts.limit, opts.cursor, opts.action),
|
|
416
454
|
)
|
|
417
455
|
|
|
418
456
|
workers, cursor = decode_worker_list_answer(response.data)
|
|
419
457
|
return WorkerListResult(workers=workers, cursor=cursor)
|
|
458
|
+
|
|
459
|
+
async def info(self, worker_id: str, namespace: str | None = None) -> WorkerDetails:
|
|
460
|
+
"""A worker's record: its row, as :meth:`list` shows it, the metadata
|
|
461
|
+
it registered with, and its processes with their run and fail counts.
|
|
462
|
+
|
|
463
|
+
Raises:
|
|
464
|
+
NotFoundError: The server doesn't know the worker.
|
|
465
|
+
"""
|
|
466
|
+
response = await self._client._send_and_check(
|
|
467
|
+
OpCode.WORKER_INFO,
|
|
468
|
+
self._client.get_namespace(namespace),
|
|
469
|
+
worker_id.encode("utf-8"),
|
|
470
|
+
b"",
|
|
471
|
+
)
|
|
472
|
+
return decode_worker_info_answer(response.data)
|
flo/client.py
CHANGED
|
@@ -15,6 +15,7 @@ from .exceptions import (
|
|
|
15
15
|
NotConnectedError,
|
|
16
16
|
ProtocolError,
|
|
17
17
|
RequestTimeoutError,
|
|
18
|
+
ServerError,
|
|
18
19
|
UnexpectedEofError,
|
|
19
20
|
raise_for_status,
|
|
20
21
|
)
|
|
@@ -23,7 +24,7 @@ from .types import _DEFAULT_WORKER_BLOCK_MS, HEADER_SIZE, OpCode, OptionTag, Sta
|
|
|
23
24
|
from .wire import (
|
|
24
25
|
OptionsIterator,
|
|
25
26
|
RawResponse,
|
|
26
|
-
|
|
27
|
+
compute_crc32c,
|
|
27
28
|
parse_response_header,
|
|
28
29
|
serialize_request,
|
|
29
30
|
)
|
|
@@ -387,7 +388,7 @@ class FloClient:
|
|
|
387
388
|
except asyncio.TimeoutError as e:
|
|
388
389
|
raise RequestTimeoutError(f"No response to {op_code.name}") from e
|
|
389
390
|
|
|
390
|
-
status, data_len, resp_request_id, crc = parse_response_header(header_data)
|
|
391
|
+
status, data_len, resp_request_id, crc, stale = parse_response_header(header_data)
|
|
391
392
|
|
|
392
393
|
if data_len > 0:
|
|
393
394
|
try:
|
|
@@ -406,10 +407,10 @@ class FloClient:
|
|
|
406
407
|
else:
|
|
407
408
|
response_data = b""
|
|
408
409
|
|
|
409
|
-
computed_crc =
|
|
410
|
+
computed_crc = compute_crc32c(header_data, response_data)
|
|
410
411
|
if computed_crc != crc:
|
|
411
412
|
raise InvalidChecksumError(
|
|
412
|
-
f"
|
|
413
|
+
f"CRC32C mismatch: 0x{computed_crc:08X} != 0x{crc:08X}"
|
|
413
414
|
)
|
|
414
415
|
if resp_request_id == 0:
|
|
415
416
|
# The server answers a request it could not parse with
|
|
@@ -435,7 +436,9 @@ class FloClient:
|
|
|
435
436
|
if self._debug:
|
|
436
437
|
logger.debug(f"[flo] <- {status.name} {len(response_data)} bytes")
|
|
437
438
|
|
|
438
|
-
return RawResponse(
|
|
439
|
+
return RawResponse(
|
|
440
|
+
status=status, data=response_data, request_id=resp_request_id, stale=stale
|
|
441
|
+
)
|
|
439
442
|
|
|
440
443
|
async def _send_and_check(
|
|
441
444
|
self,
|
|
@@ -471,7 +474,11 @@ class FloClient:
|
|
|
471
474
|
if allow_not_found and response.status == StatusCode.NOT_FOUND:
|
|
472
475
|
return response
|
|
473
476
|
|
|
474
|
-
|
|
477
|
+
try:
|
|
478
|
+
raise_for_status(response.status, response.data)
|
|
479
|
+
except ServerError as e:
|
|
480
|
+
e.stale = response.stale
|
|
481
|
+
raise
|
|
475
482
|
return response # Unreachable, but makes type checker happy
|
|
476
483
|
|
|
477
484
|
def get_namespace(self, override: str | None) -> str:
|
flo/exceptions.py
CHANGED
|
@@ -101,7 +101,7 @@ class TableMismatchError(ProtocolError):
|
|
|
101
101
|
|
|
102
102
|
|
|
103
103
|
class InvalidChecksumError(ProtocolError):
|
|
104
|
-
"""
|
|
104
|
+
"""A frame's CRC32C checksum didn't match."""
|
|
105
105
|
|
|
106
106
|
pass
|
|
107
107
|
|
|
@@ -166,6 +166,9 @@ class ServerError(FloError):
|
|
|
166
166
|
reason: Reason = Reason.UNCLASSIFIED
|
|
167
167
|
# Whether the request took effect; unknown unless the server said.
|
|
168
168
|
ran: Ran = Ran.UNKNOWN
|
|
169
|
+
# A halted shard answered, from its state just before the entry it
|
|
170
|
+
# halted at.
|
|
171
|
+
stale: bool = False
|
|
169
172
|
|
|
170
173
|
def __init__(self, message: str, status_code: StatusCode):
|
|
171
174
|
super().__init__(message)
|
|
@@ -179,6 +182,24 @@ class NotFoundError(ServerError):
|
|
|
179
182
|
super().__init__(message, StatusCode.NOT_FOUND)
|
|
180
183
|
|
|
181
184
|
|
|
185
|
+
class StaleNotFoundError(NotFoundError):
|
|
186
|
+
"""A halted shard didn't have the key, as of the entry it halted at
|
|
187
|
+
(``stale`` is True). It may exist since: a write after the halt hasn't
|
|
188
|
+
applied. kv.get and kv.json_get raise it rather than report the key
|
|
189
|
+
absent."""
|
|
190
|
+
|
|
191
|
+
stale = True
|
|
192
|
+
|
|
193
|
+
|
|
194
|
+
class NoNamespaceError(ServerError):
|
|
195
|
+
"""The namespace the request names doesn't exist. Not a NotFoundError,
|
|
196
|
+
which means a missing key, so a missing namespace never reads as an
|
|
197
|
+
absent key."""
|
|
198
|
+
|
|
199
|
+
def __init__(self, message: str = StatusCode.NO_NAMESPACE.message()):
|
|
200
|
+
super().__init__(message, StatusCode.NO_NAMESPACE)
|
|
201
|
+
|
|
202
|
+
|
|
182
203
|
class BadRequestError(ServerError):
|
|
183
204
|
"""Invalid request parameters."""
|
|
184
205
|
|
|
@@ -218,13 +239,25 @@ class UnavailableError(ServerError):
|
|
|
218
239
|
"""No leader, or the shard isn't taking writes or is offline. Retryable.
|
|
219
240
|
|
|
220
241
|
The message says why; an offline shard stays unavailable until an
|
|
221
|
-
operator acts, so whether and when to retry is the caller's call.
|
|
242
|
+
operator acts, so whether and when to retry is the caller's call. With
|
|
243
|
+
reason SHARD_HALTED the shard halted and takes no writes until an
|
|
244
|
+
operator repairs it; the client doesn't retry that one.
|
|
222
245
|
"""
|
|
223
246
|
|
|
224
247
|
def __init__(self, message: str = StatusCode.UNAVAILABLE.message()):
|
|
225
248
|
super().__init__(message, StatusCode.UNAVAILABLE)
|
|
226
249
|
|
|
227
250
|
|
|
251
|
+
class OutcomePendingError(ServerError):
|
|
252
|
+
"""The write committed but hasn't applied: its shard halted at or before
|
|
253
|
+
it (reason SHARD_HALTED, ran UNKNOWN). The message says whether it
|
|
254
|
+
applies when the shard resumes. Never retried: resending it would write
|
|
255
|
+
it twice, or halt again."""
|
|
256
|
+
|
|
257
|
+
def __init__(self, message: str = StatusCode.OUTCOME_PENDING.message()):
|
|
258
|
+
super().__init__(message, StatusCode.OUTCOME_PENDING)
|
|
259
|
+
|
|
260
|
+
|
|
228
261
|
class InternalServerError(ServerError):
|
|
229
262
|
"""Internal server error. Not retryable: the server uses it for a write
|
|
230
263
|
that committed but wasn't applied, which must not be resent."""
|
|
@@ -287,11 +320,13 @@ def _error_for(status: StatusCode, message: str) -> ServerError:
|
|
|
287
320
|
|
|
288
321
|
error_map: dict[StatusCode, Callable[[str], ServerError]] = {
|
|
289
322
|
StatusCode.NOT_FOUND: NotFoundError,
|
|
323
|
+
StatusCode.NO_NAMESPACE: NoNamespaceError,
|
|
290
324
|
StatusCode.BAD_REQUEST: BadRequestError,
|
|
291
325
|
StatusCode.CONFLICT: ConflictError,
|
|
292
326
|
StatusCode.UNAUTHORIZED: UnauthorizedError,
|
|
293
327
|
StatusCode.OVERLOADED: OverloadedError,
|
|
294
328
|
StatusCode.UNAVAILABLE: UnavailableError,
|
|
329
|
+
StatusCode.OUTCOME_PENDING: OutcomePendingError,
|
|
295
330
|
StatusCode.RATE_LIMITED: RateLimitedError,
|
|
296
331
|
StatusCode.INTERNAL_ERROR: InternalServerError,
|
|
297
332
|
StatusCode.ERROR_GENERIC: GenericServerError,
|
flo/kv.py
CHANGED
|
@@ -6,7 +6,12 @@ Key-value store operations for Flo client.
|
|
|
6
6
|
import json
|
|
7
7
|
from typing import TYPE_CHECKING, Any
|
|
8
8
|
|
|
9
|
-
from .exceptions import
|
|
9
|
+
from .exceptions import (
|
|
10
|
+
IncompleteResponseError,
|
|
11
|
+
ServerError,
|
|
12
|
+
StaleNotFoundError,
|
|
13
|
+
raise_for_status,
|
|
14
|
+
)
|
|
10
15
|
from .kv_body import (
|
|
11
16
|
decode_delete_answer,
|
|
12
17
|
decode_empty_answer,
|
|
@@ -36,10 +41,12 @@ from .kv_body import (
|
|
|
36
41
|
)
|
|
37
42
|
from .types import (
|
|
38
43
|
DeleteOptions,
|
|
44
|
+
ExistsResult,
|
|
39
45
|
GetJsonResult,
|
|
40
46
|
GetOptions,
|
|
41
47
|
GetResult,
|
|
42
48
|
HistoryOptions,
|
|
49
|
+
HistoryResult,
|
|
43
50
|
IncrResult,
|
|
44
51
|
KVExistsOptions,
|
|
45
52
|
KVExpireOptions,
|
|
@@ -53,7 +60,6 @@ from .types import (
|
|
|
53
60
|
Reason,
|
|
54
61
|
ScanOptions,
|
|
55
62
|
ScanResult,
|
|
56
|
-
VersionEntry,
|
|
57
63
|
)
|
|
58
64
|
from .wire import RawResponse
|
|
59
65
|
|
|
@@ -66,17 +72,24 @@ def _key(key: str | bytes) -> bytes:
|
|
|
66
72
|
return key.encode("utf-8") if isinstance(key, str) else key
|
|
67
73
|
|
|
68
74
|
|
|
69
|
-
def _absent(response: RawResponse) -> bool:
|
|
75
|
+
def _absent(response: RawResponse, *, stale_raises: bool = False) -> bool:
|
|
70
76
|
"""Whether a not-found answer says the thing is absent; any other not-found
|
|
71
|
-
(no such transaction) is raised.
|
|
77
|
+
(no such transaction) is raised. With stale_raises, an absent key on a
|
|
78
|
+
stale answer raises StaleNotFoundError: absent as of the halt is not
|
|
79
|
+
absent."""
|
|
72
80
|
if not response.is_not_found():
|
|
73
81
|
return False
|
|
74
82
|
try:
|
|
75
83
|
raise_for_status(response.status, response.data)
|
|
76
84
|
except ServerError as e:
|
|
77
|
-
|
|
78
|
-
|
|
79
|
-
|
|
85
|
+
e.stale = response.stale
|
|
86
|
+
if e.reason != Reason.NOT_FOUND:
|
|
87
|
+
raise
|
|
88
|
+
if stale_raises and response.stale:
|
|
89
|
+
stale = StaleNotFoundError(str(e))
|
|
90
|
+
stale.reason, stale.ran = e.reason, e.ran
|
|
91
|
+
raise stale from None
|
|
92
|
+
return True
|
|
80
93
|
return False # pragma: no cover - raise_for_status always raises here
|
|
81
94
|
|
|
82
95
|
|
|
@@ -87,9 +100,11 @@ async def kv_get(
|
|
|
87
100
|
response = await client._send_and_check(
|
|
88
101
|
OpCode.KV_GET, namespace, _key(key), encode_get_body(opts, txn), allow_not_found=True
|
|
89
102
|
)
|
|
90
|
-
if _absent(response):
|
|
103
|
+
if _absent(response, stale_raises=True):
|
|
91
104
|
return None
|
|
92
|
-
|
|
105
|
+
result = decode_get_answer(response.data)
|
|
106
|
+
result.stale = response.stale
|
|
107
|
+
return result
|
|
93
108
|
|
|
94
109
|
|
|
95
110
|
async def kv_set(
|
|
@@ -163,12 +178,14 @@ async def kv_exists(
|
|
|
163
178
|
key: str | bytes,
|
|
164
179
|
opts: KVExistsOptions,
|
|
165
180
|
txn: int | None = None,
|
|
166
|
-
) ->
|
|
181
|
+
) -> ExistsResult:
|
|
167
182
|
"""kv.exists, inside transaction ``txn`` when given."""
|
|
168
183
|
response = await client._send_and_check(
|
|
169
184
|
OpCode.KV_EXISTS, namespace, _key(key), encode_exists_body(opts.routing_key, txn)
|
|
170
185
|
)
|
|
171
|
-
|
|
186
|
+
result = decode_exists_answer(response.data)
|
|
187
|
+
result.stale = response.stale
|
|
188
|
+
return result
|
|
172
189
|
|
|
173
190
|
|
|
174
191
|
class KVOperations:
|
|
@@ -184,8 +201,15 @@ class KVOperations:
|
|
|
184
201
|
) -> GetResult | None:
|
|
185
202
|
"""Get value and version for a key.
|
|
186
203
|
|
|
187
|
-
Returns ``GetResult(value, version)``, or ``None`` if
|
|
188
|
-
found, also when a wait (``wait_ms``) ends without it.
|
|
204
|
+
Returns ``GetResult(value, version, expires_at_ms)``, or ``None`` if
|
|
205
|
+
the key is not found, also when a wait (``wait_ms``) ends without it.
|
|
206
|
+
``expires_at_ms`` is when the key's TTL runs out (unix ms), ``None``
|
|
207
|
+
when it has none. ``stale`` says a halted shard answered.
|
|
208
|
+
|
|
209
|
+
Raises:
|
|
210
|
+
NoNamespaceError: The namespace was never created.
|
|
211
|
+
StaleNotFoundError: A halted shard had no such key as of the entry
|
|
212
|
+
it halted at; it may exist since.
|
|
189
213
|
|
|
190
214
|
Example:
|
|
191
215
|
result = await client.kv.get("user:123")
|
|
@@ -281,6 +305,8 @@ class KVOperations:
|
|
|
281
305
|
)
|
|
282
306
|
if next_index == 0:
|
|
283
307
|
raise IncompleteResponseError("kv.mget answered none of the keys asked")
|
|
308
|
+
for e in entries:
|
|
309
|
+
e.stale = response.stale
|
|
284
310
|
out.extend(entries)
|
|
285
311
|
done += len(entries)
|
|
286
312
|
return out
|
|
@@ -293,13 +319,14 @@ class KVOperations:
|
|
|
293
319
|
"""List the names of keys with a prefix ("" for all), a page at a time.
|
|
294
320
|
|
|
295
321
|
Example:
|
|
296
|
-
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
|
|
300
|
-
|
|
301
|
-
|
|
302
|
-
|
|
322
|
+
opts = ScanOptions()
|
|
323
|
+
while True:
|
|
324
|
+
result = await client.kv.scan("user:", opts)
|
|
325
|
+
for name in result.names:
|
|
326
|
+
print(name)
|
|
327
|
+
if result.cursor is None:
|
|
328
|
+
break
|
|
329
|
+
opts = ScanOptions(cursor=result.cursor)
|
|
303
330
|
"""
|
|
304
331
|
opts = options or ScanOptions()
|
|
305
332
|
response = await self._client._send_and_check(
|
|
@@ -309,31 +336,41 @@ class KVOperations:
|
|
|
309
336
|
encode_scan_body(opts.limit, opts.cursor),
|
|
310
337
|
)
|
|
311
338
|
names, cursor = decode_scan_answer(response.data)
|
|
312
|
-
return ScanResult(names=names, cursor=cursor)
|
|
339
|
+
return ScanResult(names=names, cursor=cursor, stale=response.stale)
|
|
313
340
|
|
|
314
341
|
async def history(
|
|
315
342
|
self,
|
|
316
343
|
key: str | bytes,
|
|
317
344
|
options: HistoryOptions | None = None,
|
|
318
|
-
) ->
|
|
319
|
-
"""A key's versions, newest first, each with when it was
|
|
320
|
-
|
|
345
|
+
) -> HistoryResult:
|
|
346
|
+
"""A page of a key's versions, newest first, each with when it was
|
|
347
|
+
written and whether it was a delete (``deleted``, with an empty
|
|
348
|
+
value); empty for a missing key. ``more`` says older kept versions
|
|
349
|
+
follow: ask again with ``before_version`` set to the last version of
|
|
350
|
+
this page.
|
|
321
351
|
|
|
322
352
|
Example:
|
|
323
|
-
|
|
324
|
-
|
|
353
|
+
opts = HistoryOptions(limit=10)
|
|
354
|
+
while True:
|
|
355
|
+
page = await client.kv.history("user:123", opts)
|
|
356
|
+
for entry in page.versions:
|
|
357
|
+
print(f"v{entry.version} at {entry.at_ms}: {entry.value}")
|
|
358
|
+
if not page.more or not page.versions:
|
|
359
|
+
break
|
|
360
|
+
opts = HistoryOptions(limit=10, before_version=page.versions[-1].version)
|
|
325
361
|
"""
|
|
326
362
|
opts = options or HistoryOptions()
|
|
327
363
|
response = await self._client._send_and_check(
|
|
328
364
|
OpCode.KV_HISTORY,
|
|
329
365
|
self._client.get_namespace(opts.namespace),
|
|
330
366
|
_key(key),
|
|
331
|
-
encode_history_body(opts.limit, opts.routing_key),
|
|
367
|
+
encode_history_body(opts.limit, opts.before_version, opts.routing_key),
|
|
332
368
|
allow_not_found=True,
|
|
333
369
|
)
|
|
334
370
|
if _absent(response):
|
|
335
|
-
return []
|
|
336
|
-
|
|
371
|
+
return HistoryResult(versions=[], more=False, stale=response.stale)
|
|
372
|
+
versions, more = decode_history_answer(response.data)
|
|
373
|
+
return HistoryResult(versions=versions, more=more, stale=response.stale)
|
|
337
374
|
|
|
338
375
|
# ── Counters, TTL, exists, JSON paths ──────────────────────────────
|
|
339
376
|
|
|
@@ -373,8 +410,8 @@ class KVOperations:
|
|
|
373
410
|
self,
|
|
374
411
|
key: str | bytes,
|
|
375
412
|
options: KVExistsOptions | None = None,
|
|
376
|
-
) ->
|
|
377
|
-
"""
|
|
413
|
+
) -> ExistsResult:
|
|
414
|
+
"""Whether ``key`` is present, and its version, without transferring its value."""
|
|
378
415
|
opts = options or KVExistsOptions()
|
|
379
416
|
return await kv_exists(self._client, self._client.get_namespace(opts.namespace), key, opts)
|
|
380
417
|
|
|
@@ -388,7 +425,8 @@ class KVOperations:
|
|
|
388
425
|
|
|
389
426
|
Returns a :class:`GetJsonResult` whose ``value`` is the parsed JSON,
|
|
390
427
|
with the document's current version, or ``None`` if the key or path
|
|
391
|
-
is missing.
|
|
428
|
+
is missing. A missing key on a halted shard's answer raises
|
|
429
|
+
:class:`StaleNotFoundError` instead.
|
|
392
430
|
"""
|
|
393
431
|
opts = options or KVJsonOptions()
|
|
394
432
|
response = await self._client._send_and_check(
|
|
@@ -398,10 +436,12 @@ class KVOperations:
|
|
|
398
436
|
encode_json_get_body(path, opts.routing_key),
|
|
399
437
|
allow_not_found=True,
|
|
400
438
|
)
|
|
401
|
-
if _absent(response):
|
|
439
|
+
if _absent(response, stale_raises=True):
|
|
402
440
|
return None
|
|
403
441
|
version, document = decode_json_get_answer(response.data)
|
|
404
|
-
return GetJsonResult(
|
|
442
|
+
return GetJsonResult(
|
|
443
|
+
value=json.loads(document.decode("utf-8")), version=version, stale=response.stale
|
|
444
|
+
)
|
|
405
445
|
|
|
406
446
|
async def json_set(
|
|
407
447
|
self,
|