ivcap-lambda 0.8.5__tar.gz → 0.8.6__tar.gz

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.
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: ivcap-lambda
3
- Version: 0.8.5
3
+ Version: 0.8.6
4
4
  Summary: Helper functions for building lambda-style services on the IVCAP platform
5
5
  License-File: AUTHORS.md
6
6
  License-File: LICENSE
@@ -21,6 +21,7 @@ from .executor import (
21
21
  from .executor import (
22
22
  get_job_id as get_job_id,
23
23
  )
24
+ from .health_handler import NotReadyYet as NotReadyYet
24
25
  from .logger import logging_init as logging_init
25
26
  from .secret import SecretMgrClient as SecretMgrClient
26
27
  from .server import (
@@ -65,8 +65,12 @@ class ToolOptions(BaseModel):
65
65
  service_id: str | None = Field(
66
66
  None, description="overriding the default service id"
67
67
  )
68
- is_ready: Callable[[], bool] | None = Field(
69
- None, description="Function to check if the tool is ready"
68
+ is_ready: Callable[[], bool | dict[str, Any]] | None = Field(
69
+ None,
70
+ description=(
71
+ "Readiness check. Return a dict of info to report on /_healtz (or True), "
72
+ "return False, or raise NotReadyYet(retry_after) while not ready"
73
+ ),
70
74
  )
71
75
 
72
76
 
@@ -0,0 +1,93 @@
1
+ from __future__ import annotations
2
+
3
+ import asyncio
4
+ import math
5
+ import os
6
+ from collections.abc import Awaitable, Callable
7
+ from typing import Any
8
+
9
+ from fastapi import FastAPI, HTTPException
10
+
11
+ from .utils import find_first
12
+
13
+ # A readiness check returns True (ready), False (legacy not-ready), or a dict of
14
+ # extra info to add to the health reply (ready). Raising NotReadyYet also means
15
+ # not-ready. Sync or async.
16
+ ReadyFn = Callable[[], bool | dict[str, Any] | Awaitable[bool | dict[str, Any]]]
17
+
18
+ # Global registry of readiness handlers
19
+ _ready_handlers: list[ReadyFn] = []
20
+
21
+
22
+ class NotReadyYet(Exception):
23
+ """Raised by an `is_ready` callback when the tool is not ready yet.
24
+
25
+ Args:
26
+ retry_after: optional expected time in seconds until the tool is ready.
27
+ Reported to callers as the `Retry-After` header on `/_healtz`.
28
+ """
29
+
30
+ def __init__(self, retry_after: float | None = None):
31
+ super().__init__("Not ready yet")
32
+ self.retry_after = retry_after
33
+
34
+
35
+ def add_ready_handler(ready_fn: ReadyFn | None) -> None:
36
+ """
37
+ Register a readiness handler in the global list. Called from builder when
38
+ a tool is registered with opts.is_ready set.
39
+ """
40
+ if ready_fn is not None:
41
+ _ready_handlers.append(ready_fn)
42
+
43
+
44
+ async def healtz_handler() -> dict:
45
+ """
46
+ Check all registered readiness handlers.
47
+
48
+ - Dict results are merged into the reply. `version` always wins over a
49
+ key of the same name.
50
+ - If every handler is ready (True, a dict, or no handlers at all), return
51
+ {"version": ..., **extra_info}.
52
+ - If any handler returns False or raises NotReadyYet, raise a 503. When
53
+ NotReadyYet carries retry_after, the largest value is sent as the
54
+ `Retry-After` header in whole seconds (rounded up).
55
+ """
56
+ info: dict[str, Any] = {}
57
+ not_ready = False
58
+ retry_after: float | None = None
59
+
60
+ for handler in _ready_handlers:
61
+ try:
62
+ result: Any = handler()
63
+ if asyncio.iscoroutine(result):
64
+ result = await result
65
+ except NotReadyYet as ex:
66
+ not_ready = True
67
+ if ex.retry_after is not None:
68
+ retry_after = max(retry_after or 0.0, ex.retry_after)
69
+ continue
70
+
71
+ if isinstance(result, dict):
72
+ info.update(result)
73
+ elif not result:
74
+ not_ready = True
75
+
76
+ if not_ready:
77
+ headers = None
78
+ if retry_after is not None:
79
+ headers = {"Retry-After": str(max(0, math.ceil(retry_after)))}
80
+ raise HTTPException(
81
+ status_code=503, detail="Service Unavailable", headers=headers
82
+ )
83
+
84
+ return {**info, "version": os.environ.get("VERSION", "???")}
85
+
86
+
87
+ def add_health_route(app: FastAPI) -> None:
88
+ """
89
+ Register `GET /_healtz` backed by `healtz_handler`, unless the app already
90
+ serves that path.
91
+ """
92
+ if find_first(app.routes, lambda r: r.path == "/_healtz") is None:
93
+ app.add_api_route("/_healtz", healtz_handler, methods=["GET"], tags=["System"])
@@ -33,7 +33,7 @@ from opentelemetry.instrumentation.fastapi import FastAPIInstrumentor
33
33
  # from .context import set_context, otel_instrument
34
34
  from .builder import tools
35
35
  from .executor import Executor, get_job_context
36
- from .utils import find_first
36
+ from .health_handler import add_health_route
37
37
  from .version import get_version
38
38
 
39
39
  # shutdown pod cracefully
@@ -236,13 +236,7 @@ def start_lambda_server(
236
236
  run_mcp_stdio(service.name, app.version)
237
237
  return
238
238
 
239
- # Check for '_healtz' service
240
- healtz = find_first(app.routes, lambda r: r.path == "/_healtz")
241
- if healtz is None:
242
-
243
- @app.get("/_healtz", tags=["System"])
244
- def healtz():
245
- return {"version": os.environ.get("VERSION", "???")}
239
+ add_health_route(app)
246
240
 
247
241
  if args.with_mcp:
248
242
  from .mcp import register_mcp
@@ -1,6 +1,6 @@
1
1
  [tool.poetry]
2
2
  name = "ivcap-lambda"
3
- version = "0.8.5"
3
+ version = "0.8.6"
4
4
  description = "Helper functions for building lambda-style services on the IVCAP platform"
5
5
 
6
6
  authors = ["Max Ott <max.ott@csiro.au>"]
@@ -1,45 +0,0 @@
1
-
2
- from __future__ import annotations
3
-
4
- import asyncio
5
- import os
6
- from collections.abc import Awaitable, Callable
7
-
8
- from fastapi import HTTPException
9
-
10
- # Global registry of readiness handlers (sync or async callables returning bool)
11
- _ready_handlers: list[Callable[[], bool | Awaitable[bool]]] = []
12
-
13
-
14
- def add_ready_handler(ready_fn: Callable[[], bool | Awaitable[bool]] | None) -> None:
15
- """
16
- Register a readiness handler in the global list. Called from builder when
17
- a tool is registered with opts.is_ready set.
18
- """
19
- if ready_fn is not None:
20
- _ready_handlers.append(ready_fn)
21
-
22
-
23
- async def healtz_handler() -> dict:
24
- """
25
- Check all registered readiness handlers.
26
-
27
- - If there are no handlers, or all handlers report ready, return
28
- {"version": os.environ.get("VERSION", "???")}.
29
- - If any handler reports not-ready, raise a 503 Service Unavailable.
30
- """
31
-
32
- # No handlers registered -> consider service ready
33
- if not _ready_handlers:
34
- return {"version": os.environ.get("VERSION", "???")}
35
-
36
- for handler in _ready_handlers:
37
- result = handler()
38
- if asyncio.iscoroutine(result):
39
- result = await result
40
-
41
- if not result:
42
- # At least one handler reports not-ready
43
- raise HTTPException(status_code=503, detail="Service Unavailable")
44
-
45
- return {"version": os.environ.get("VERSION", "???")}
File without changes
File without changes
File without changes