kubefn 0.5.0__tar.gz

kubefn-0.5.0/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: kubefn
+Version: 0.5.0
+Summary: KubeFn Python Runtime — Live Application Fabric for Memory-Continuous Architecture
+Author-email: Pranab Sarkar <developer@pranab.co.in>
+License: MIT
+Project-URL: Homepage, https://kubefn.com
+Project-URL: GitHub, https://github.com/kubefn/kubefn
+Project-URL: Documentation, https://kubefn.com
+Project-URL: Bug Tracker, https://github.com/kubefn/kubefn/issues
+Keywords: kubefn,faas,functions,shared-memory,zero-copy,kubernetes,heap-exchange
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: System :: Distributed Computing
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown

kubefn-0.5.0/kubefn/__init__.py

@@ -0,0 +1,23 @@
+"""
+KubeFn Python Runtime — Memory-Continuous Architecture for Python.
+
+Same concept as the JVM runtime: multiple independently deployable
+functions share a single Python interpreter, exchanging objects
+in shared memory with zero serialization.
+
+    from kubefn import function, heap_exchange, KubeFnApp
+
+    @function("/predict", methods=["POST"], group="ml-pipeline")
+    def predict(request, ctx):
+        features = ctx.heap.get("features")  # Zero-copy from shared heap
+        prediction = model.predict(features)
+        ctx.heap.publish("prediction", prediction)
+        return {"score": prediction}
+"""
+
+__version__ = "0.4.0"
+
+from .decorators import function
+from .scheduler import schedule
+from .heap_exchange import HeapExchange
+from .context import FnContext, FnRequest

kubefn-0.5.0/kubefn/__main__.py

@@ -0,0 +1,110 @@
+"""
+KubeFn Python Runtime — entry point.
+
+Usage:
+    python -m kubefn
+    python -m kubefn --port 8080 --functions-dir /var/kubefn/functions
+    python -m kubefn --timeout 60000 --no-scheduler
+"""
+
+import argparse
+import os
+
+from .circuit_breaker import CircuitBreakerRegistry
+from .drain_manager import DrainManager
+from .introspection import CaptureEngine
+from .metrics import MetricsRecorder
+from .heap_guard import HeapGuard, HeapGuardConfig
+from .scheduler import SchedulerEngine
+from .server import run_server
+
+
+def main():
+    parser = argparse.ArgumentParser(description="KubeFn Python Runtime")
+    parser.add_argument(
+        "--port", type=int,
+        default=int(os.environ.get("KUBEFN_PORT", "8080")),
+    )
+    parser.add_argument(
+        "--functions-dir",
+        default=os.environ.get("KUBEFN_FUNCTIONS_DIR", "/var/kubefn/functions"),
+    )
+    parser.add_argument(
+        "--timeout", type=int,
+        default=int(os.environ.get("KUBEFN_TIMEOUT_MS", "30000")),
+        help="Request timeout in milliseconds (default: 30000)",
+    )
+    parser.add_argument(
+        "--max-heap-objects", type=int,
+        default=int(os.environ.get("KUBEFN_MAX_HEAP_OBJECTS", "10000")),
+        help="Maximum objects in HeapExchange (default: 10000)",
+    )
+    parser.add_argument(
+        "--cb-threshold", type=int,
+        default=int(os.environ.get("KUBEFN_CB_THRESHOLD", "5")),
+        help="Circuit breaker failure threshold (default: 5)",
+    )
+    parser.add_argument(
+        "--cb-reset-timeout", type=float,
+        default=float(os.environ.get("KUBEFN_CB_RESET_TIMEOUT", "30.0")),
+        help="Circuit breaker reset timeout in seconds (default: 30)",
+    )
+    parser.add_argument(
+        "--drain-timeout", type=float,
+        default=float(os.environ.get("KUBEFN_DRAIN_TIMEOUT", "30.0")),
+        help="Drain timeout in seconds (default: 30)",
+    )
+    parser.add_argument(
+        "--event-ring-capacity", type=int,
+        default=int(os.environ.get("KUBEFN_EVENT_RING_CAPACITY", "50000")),
+        help="Causal event ring buffer capacity (default: 50000)",
+    )
+    parser.add_argument(
+        "--no-scheduler", action="store_true",
+        default=os.environ.get("KUBEFN_NO_SCHEDULER", "").lower() in ("1", "true"),
+        help="Disable the cron scheduler",
+    )
+    args = parser.parse_args()
+
+    # ── Create production subsystems ──────────────────────────────────
+
+    heap_guard = HeapGuard(HeapGuardConfig(
+        max_objects=args.max_heap_objects,
+    ))
+
+    circuit_breakers = CircuitBreakerRegistry(
+        failure_threshold=args.cb_threshold,
+        reset_timeout_s=args.cb_reset_timeout,
+    )
+
+    drain_manager = DrainManager(
+        drain_timeout_s=args.drain_timeout,
+    )
+
+    capture_engine = CaptureEngine(
+        capacity=args.event_ring_capacity,
+    )
+
+    metrics_recorder = MetricsRecorder()
+
+    scheduler: SchedulerEngine | None = None
+    if not args.no_scheduler:
+        scheduler = SchedulerEngine()
+
+    # ── Start server with all subsystems ──────────────────────────────
+
+    run_server(
+        port=args.port,
+        functions_dir=args.functions_dir,
+        heap_guard=heap_guard,
+        circuit_breakers=circuit_breakers,
+        drain_manager=drain_manager,
+        capture_engine=capture_engine,
+        metrics_recorder=metrics_recorder,
+        scheduler=scheduler,
+        request_timeout_ms=args.timeout,
+    )
+
+
+if __name__ == "__main__":
+    main()

kubefn-0.5.0/kubefn/circuit_breaker.py

@@ -0,0 +1,166 @@
+"""
+Circuit Breaker — per-function fault isolation.
+
+Prevents cascading failures by tracking error rates per function
+and temporarily disabling functions that exceed the failure threshold.
+
+States:
+  CLOSED    → normal operation, requests pass through
+  OPEN      → function disabled, requests fail-fast
+  HALF_OPEN → trial period, one request allowed to test recovery
+"""
+
+import enum
+import logging
+import threading
+import time
+from dataclasses import dataclass, field
+
+logger = logging.getLogger("kubefn.circuit_breaker")
+
+
+class CircuitState(enum.Enum):
+    CLOSED = "CLOSED"
+    OPEN = "OPEN"
+    HALF_OPEN = "HALF_OPEN"
+
+
+@dataclass
+class CircuitBreaker:
+    """Per-function circuit breaker with configurable thresholds."""
+
+    function_name: str
+    failure_threshold: int = 5
+    reset_timeout_s: float = 30.0
+    half_open_max_calls: int = 1
+
+    # Internal state
+    state: CircuitState = field(default=CircuitState.CLOSED)
+    failure_count: int = field(default=0)
+    success_count: int = field(default=0)
+    last_failure_time: float = field(default=0.0)
+    last_state_change: float = field(default_factory=time.time)
+    total_rejections: int = field(default=0)
+    half_open_calls: int = field(default=0)
+    _lock: threading.Lock = field(default_factory=threading.Lock, repr=False)
+
+    def is_allowed(self) -> bool:
+        """Check if a request is allowed through this breaker."""
+        with self._lock:
+            match self.state:
+                case CircuitState.CLOSED:
+                    return True
+                case CircuitState.OPEN:
+                    if time.time() - self.last_failure_time >= self.reset_timeout_s:
+                        self._transition(CircuitState.HALF_OPEN)
+                        self.half_open_calls = 1
+                        return True
+                    self.total_rejections += 1
+                    return False
+                case CircuitState.HALF_OPEN:
+                    if self.half_open_calls < self.half_open_max_calls:
+                        self.half_open_calls += 1
+                        return True
+                    self.total_rejections += 1
+                    return False
+
+    def record_success(self) -> None:
+        """Record a successful invocation."""
+        with self._lock:
+            match self.state:
+                case CircuitState.HALF_OPEN:
+                    self.success_count += 1
+                    self._transition(CircuitState.CLOSED)
+                    self.failure_count = 0
+                case CircuitState.CLOSED:
+                    self.success_count += 1
+                    self.failure_count = 0
+
+    def record_failure(self) -> None:
+        """Record a failed invocation."""
+        with self._lock:
+            self.failure_count += 1
+            self.last_failure_time = time.time()
+
+            match self.state:
+                case CircuitState.HALF_OPEN:
+                    self._transition(CircuitState.OPEN)
+                case CircuitState.CLOSED:
+                    if self.failure_count >= self.failure_threshold:
+                        self._transition(CircuitState.OPEN)
+                        logger.warning(
+                            f"Circuit OPEN for {self.function_name}: "
+                            f"{self.failure_count} consecutive failures"
+                        )
+
+    def _transition(self, new_state: CircuitState) -> None:
+        old_state = self.state
+        self.state = new_state
+        self.last_state_change = time.time()
+        self.half_open_calls = 0
+        logger.info(
+            f"Circuit breaker [{self.function_name}]: "
+            f"{old_state.value} -> {new_state.value}"
+        )
+
+    def status(self) -> dict:
+        with self._lock:
+            return {
+                "function": self.function_name,
+                "state": self.state.value,
+                "failureCount": self.failure_count,
+                "successCount": self.success_count,
+                "totalRejections": self.total_rejections,
+                "lastFailureTime": self.last_failure_time,
+                "lastStateChange": self.last_state_change,
+                "failureThreshold": self.failure_threshold,
+                "resetTimeoutS": self.reset_timeout_s,
+            }
+
+
+class CircuitBreakerRegistry:
+    """
+    Manages per-function circuit breakers. Automatically creates
+    a breaker on first access for any function name.
+    """
+
+    def __init__(
+        self,
+        failure_threshold: int = 5,
+        reset_timeout_s: float = 30.0,
+    ):
+        self._breakers: dict[str, CircuitBreaker] = {}
+        self._lock = threading.Lock()
+        self._failure_threshold = failure_threshold
+        self._reset_timeout_s = reset_timeout_s
+
+    def _get_or_create(self, func_name: str) -> CircuitBreaker:
+        breaker = self._breakers.get(func_name)
+        if breaker is not None:
+            return breaker
+        with self._lock:
+            # Double-check after acquiring lock
+            if func_name not in self._breakers:
+                self._breakers[func_name] = CircuitBreaker(
+                    function_name=func_name,
+                    failure_threshold=self._failure_threshold,
+                    reset_timeout_s=self._reset_timeout_s,
+                )
+            return self._breakers[func_name]
+
+    def is_allowed(self, func_name: str) -> bool:
+        return self._get_or_create(func_name).is_allowed()
+
+    def record_success(self, func_name: str) -> None:
+        self._get_or_create(func_name).record_success()
+
+    def record_failure(self, func_name: str) -> None:
+        self._get_or_create(func_name).record_failure()
+
+    def get_status(self) -> dict:
+        """Return status of all known breakers."""
+        with self._lock:
+            return {
+                name: breaker.status()
+                for name, breaker in sorted(self._breakers.items())
+            }

kubefn-0.5.0/kubefn/context.py

@@ -0,0 +1,51 @@
+"""
+Function execution context — the function's window into the organism.
+"""
+
+from dataclasses import dataclass
+import logging
+from typing import Any, Optional
+
+from .heap_exchange import HeapExchange
+
+
+@dataclass
+class FnRequest:
+    """Incoming HTTP request."""
+    method: str
+    path: str
+    headers: dict[str, str]
+    query_params: dict[str, str]
+    body: bytes
+    body_text: str = ""
+
+    def query_param(self, name: str, default: str = None) -> Optional[str]:
+        return self.query_params.get(name, default)
+
+
+@dataclass
+class FnContext:
+    """
+    The function's window into the living organism.
+    Provides access to HeapExchange, cache, logging, config.
+    """
+    heap: HeapExchange
+    group_name: str
+    function_name: str
+    revision_id: str
+    config: dict[str, str]
+    _cache: dict = None
+
+    def __post_init__(self):
+        if self._cache is None:
+            self._cache = {}
+
+    @property
+    def logger(self) -> logging.Logger:
+        return logging.getLogger(f"kubefn.{self.group_name}.{self.function_name}")
+
+    def cache_get(self, key: str) -> Optional[Any]:
+        return self._cache.get(key)
+
+    def cache_put(self, key: str, value: Any):
+        self._cache[key] = value

kubefn-0.5.0/kubefn/decorators.py

@@ -0,0 +1,69 @@
+"""
+Function decorators for KubeFn Python functions.
+
+Usage:
+    from kubefn.decorators import function
+
+    @function("/predict", methods=["POST"], group="ml-pipeline")
+    def predict(request, ctx):
+        return {"prediction": 0.95}
+"""
+
+import functools
+from dataclasses import dataclass, field
+
+
+@dataclass
+class FunctionMetadata:
+    """Metadata extracted from the @function decorator."""
+    path: str
+    methods: list[str]
+    group: str
+    name: str
+    handler: callable
+
+
+# Global registry of decorated functions
+_registry: list[FunctionMetadata] = []
+
+
+def function(path: str, methods: list[str] = None, group: str = "default"):
+    """
+    Decorator that registers a Python function as a KubeFn handler.
+
+    @function("/predict", methods=["POST"], group="ml-pipeline")
+    def predict(request, ctx):
+        features = ctx.heap.get("features")
+        return {"prediction": model.predict(features)}
+    """
+    if methods is None:
+        methods = ["GET", "POST"]
+
+    def decorator(func):
+        metadata = FunctionMetadata(
+            path=path,
+            methods=methods,
+            group=group,
+            name=func.__name__,
+            handler=func,
+        )
+        _registry.append(metadata)
+
+        @functools.wraps(func)
+        def wrapper(*args, **kwargs):
+            return func(*args, **kwargs)
+
+        wrapper._kubefn_metadata = metadata
+        return wrapper
+
+    return decorator
+
+
+def get_registered_functions() -> list[FunctionMetadata]:
+    """Get all registered function handlers."""
+    return list(_registry)
+
+
+def clear_registry():
+    """Clear the function registry (used during hot-reload)."""
+    _registry.clear()

kubefn-0.5.0/kubefn/drain_manager.py

@@ -0,0 +1,115 @@
+"""
+Drain Manager — graceful shutdown and hot-swap coordination.
+
+Tracks in-flight requests and supports draining: rejecting new requests
+while allowing in-flight requests to complete before shutdown or reload.
+"""
+
+import logging
+import threading
+import time
+
+logger = logging.getLogger("kubefn.drain")
+
+
+class DrainManager:
+    """
+    Thread-safe drain coordinator. Used during graceful shutdown
+    and function hot-swap to ensure zero dropped requests.
+
+    Usage:
+        if not drain.acquire():
+            return 503  # draining, reject
+        try:
+            handle_request()
+        finally:
+            drain.release()
+    """
+
+    def __init__(self, drain_timeout_s: float = 30.0):
+        self._lock = threading.Lock()
+        self._drained = threading.Event()
+        self._draining = False
+        self._in_flight = 0
+        self._drain_timeout_s = drain_timeout_s
+        self._drain_started_at: float | None = None
+
+    def acquire(self) -> bool:
+        """
+        Attempt to acquire a request slot.
+        Returns False if the system is draining (caller should return 503).
+        """
+        with self._lock:
+            if self._draining:
+                return False
+            self._in_flight += 1
+            self._drained.clear()
+            return True
+
+    def release(self) -> None:
+        """Release a request slot after handling completes."""
+        with self._lock:
+            self._in_flight -= 1
+            if self._in_flight <= 0:
+                self._in_flight = 0
+                self._drained.set()
+
+    def start_drain(self, timeout_s: float | None = None) -> bool:
+        """
+        Begin draining. Blocks until all in-flight requests complete
+        or the timeout expires.
+
+        Returns True if drain completed (in-flight reached 0),
+        False if timed out.
+        """
+        timeout = timeout_s if timeout_s is not None else self._drain_timeout_s
+
+        with self._lock:
+            self._draining = True
+            self._drain_started_at = time.time()
+            if self._in_flight == 0:
+                self._drained.set()
+                logger.info("Drain: no in-flight requests, drained immediately")
+                return True
+
+        logger.info(
+            f"Drain started: {self._in_flight} in-flight requests, "
+            f"timeout={timeout}s"
+        )
+
+        drained = self._drained.wait(timeout=timeout)
+
+        if drained:
+            logger.info("Drain complete: all in-flight requests finished")
+        else:
+            logger.warning(
+                f"Drain timed out after {timeout}s with "
+                f"{self._in_flight} requests still in-flight"
+            )
+
+        return drained
+
+    def cancel_drain(self) -> None:
+        """Cancel an active drain (e.g. if reload was aborted)."""
+        with self._lock:
+            self._draining = False
+            self._drain_started_at = None
+        logger.info("Drain cancelled")
+
+    def is_draining(self) -> bool:
+        return self._draining
+
+    def in_flight_count(self) -> int:
+        return self._in_flight
+
+    def status(self) -> dict:
+        with self._lock:
+            result: dict = {
+                "draining": self._draining,
+                "inFlight": self._in_flight,
+                "drainTimeoutS": self._drain_timeout_s,
+            }
+            if self._drain_started_at is not None:
+                result["drainStartedAt"] = self._drain_started_at
+                result["drainElapsedS"] = round(time.time() - self._drain_started_at, 2)
+            return result