specter-runtime 0.1.1__py3-none-any.whl

specter/__init__.py

@@ -0,0 +1,136 @@
+# Copyright 2026 BleedingXiko
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+SPECTER — Service Primitives for Event Control, Teardown, and Execution Runtime
+================================================================================
+
+Lifecycle-first backend framework for Python, Flask, and gevent.
+Provides explicit ownership, deterministic cleanup, and clear service
+boundaries for Flask/gevent/SQLite applications.
+
+**Framework Surface:**
+
++--------------------+----------------------------------+
+| Channel            | Role                             |
++====================+==================================+
+| ``Service``        | Background lifecycle owner       |
++--------------------+----------------------------------+
+| ``QueueService``   | Queue-backed worker lifecycle    |
++--------------------+----------------------------------+
+| ``Controller``     | Feature composition root         |
++--------------------+----------------------------------+
+| ``Handler``        | Socket event lifecycle owner     |
++--------------------+----------------------------------+
+| ``create_model``   | Structured state graph           |
++--------------------+----------------------------------+
+| ``create_store``   | Shared mutable state             |
++--------------------+----------------------------------+
+| ``create_cache``   | Shared state with TTL + cascade  |
++--------------------+----------------------------------+
+| ``ManagedProcess`` | Subprocess + stream ownership    |
++--------------------+----------------------------------+
+| ``Watcher``        | Observation loop primitive       |
++--------------------+----------------------------------+
+| ``Schema``         | Payload contract / validation    |
++--------------------+----------------------------------+
+| ``Outcome``        | Structured operation result      |
++--------------------+----------------------------------+
+| ``Operation``      | Structured backend action        |
++--------------------+----------------------------------+
+| ``Router``         | Class-based HTTP composition     |
++--------------------+----------------------------------+
+| ``registry``       | Composition-root service locator |
++--------------------+----------------------------------+
+| ``bus``            | Internal pub/sub                 |
++--------------------+----------------------------------+
+| ``json_endpoint``  | Flask route envelope helpers     |
++--------------------+----------------------------------+
+
+**Import from here:**
+
+    from specter import (
+        Service, QueueService, Controller, Handler, create_store,
+        create_cache, Watcher, Schema, Field,
+        registry, bus, HTTPError, json_endpoint, expect_json,
+    )
+
+See ``specter.md`` for the full guide.
+"""
+
+# Core primitives
+from .core.lifecycle import Service
+from .core.queue_service import QueueService
+from .core.controller import Controller
+from .core.process import ManagedProcess, start_process
+from .core.watcher import Watcher, WatcherError
+from .core.model import Model, create_model
+from .core.schema import Schema, Field, SchemaError
+from .core.outcome import Outcome
+from .core.operation import Operation, OperationError
+from .core.store import Store, create_store
+from .core.handler import Handler
+from .core.cache import Cache, create_cache
+from .core.bus import EventBus, bus
+from .core.registry import SPECTERRegistry, registry
+from .core.manager import ServiceManager
+from .core.socket_ingress import SocketIngress
+from .http import HTTPError, json_endpoint, expect_json, require_fields
+from .router import Router, route
+from .boot import boot
+
+__version__ = '0.1.1'
+
+__all__ = [
+    # Lifecycle
+    'Service',
+    'QueueService',
+    'Controller',
+    'ManagedProcess',
+    'start_process',
+    'Watcher',
+    'WatcherError',
+    'Outcome',
+    'Operation',
+    'OperationError',
+    'Router',
+    'route',
+    'Handler',
+    'ServiceManager',
+    'SocketIngress',
+    'boot',
+    # State
+    'Model',
+    'create_model',
+    'Store',
+    'create_store',
+    'Cache',
+    'create_cache',
+    # Contracts
+    'Schema',
+    'Field',
+    'SchemaError',
+    # Communication
+    'EventBus',
+    'bus',
+    # Registry
+    'SPECTERRegistry',
+    'registry',
+    # HTTP
+    'HTTPError',
+    'json_endpoint',
+    'expect_json',
+    'require_fields',
+    '__version__',
+]

specter/boot.py

@@ -0,0 +1,53 @@
+# Copyright 2026 BleedingXiko
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""SPECTER boot helpers for app-level composition roots."""
+
+from .core.manager import ServiceManager
+
+
+def boot(
+    app,
+    socketio,
+    *,
+    services=None,
+    handlers=None,
+    controllers=None,
+):
+    """
+    Create and boot a ``ServiceManager`` with the supplied components.
+
+    Args:
+        app: Flask app instance.
+        socketio: Flask-SocketIO instance.
+        services: Optional iterable of ``Service`` instances.
+        handlers: Optional iterable of handler instances.
+        controllers: Optional iterable of ``Controller`` instances.
+
+    Returns:
+        A booted ``ServiceManager``.
+    """
+    manager = ServiceManager(app, socketio)
+
+    for service in services or ():
+        manager.register_service(service)
+
+    for handler in handlers or ():
+        manager.register_handler(handler)
+
+    for controller in controllers or ():
+        manager.register_controller(controller)
+
+    manager.boot()
+    return manager

specter/core/__init__.py

@@ -0,0 +1,37 @@
+# Copyright 2026 BleedingXiko
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""SPECTER Core — internal primitives."""
+
+from .lifecycle import Service
+from .queue_service import QueueService
+from .process import ManagedProcess, start_process
+from .model import Model, create_model
+from .outcome import Outcome
+from .operation import Operation, OperationError
+from .store import Store, create_store
+
+__all__ = [
+    'Service',
+    'QueueService',
+    'ManagedProcess',
+    'start_process',
+    'Model',
+    'create_model',
+    'Outcome',
+    'Operation',
+    'OperationError',
+    'Store',
+    'create_store',
+]

specter/core/bus.py

@@ -0,0 +1,163 @@
+# Copyright 2026 BleedingXiko
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+SPECTER EventBus — Internal pub/sub for cross-service communication.
+
+Decoupled broadcast semantics so services can react to events without
+importing each other directly.
+
+NOTE: This bus is for **internal server-side** events only.
+Socket events go through ``socketio.emit()``.
+
+Concurrency model:
+    Subscribers run synchronously in the emitter's greenlet.
+    If a subscriber needs to do heavy work, it should spawn its own
+    greenlet via ``gevent.spawn()``.
+"""
+
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class EventBus:
+    """Global event bus for decoupled service communication."""
+
+    def __init__(self):
+        self._events = {}  # event_name -> set of callbacks
+
+    # ------------------------------------------------------------------
+    # Subscribe
+    # ------------------------------------------------------------------
+
+    def on(self, event, callback):
+        """
+        Subscribe to an event.
+
+        Args:
+            event: Event name string.
+            callback: Function to call when event is emitted. Receives
+                      a single ``data`` argument (may be ``None``).
+
+        Returns:
+            An unsubscribe function.
+        """
+        if not callable(callback):
+            raise TypeError(
+                f"[SPECTER:bus] on('{event}'): callback must be callable, "
+                f"got {type(callback).__name__}"
+            )
+        if event not in self._events:
+            self._events[event] = set()
+        self._events[event].add(callback)
+        return lambda: self.off(event, callback)
+
+    def off(self, event, callback):
+        """
+        Unsubscribe from an event.
+
+        Args:
+            event: Event name
+            callback: The exact callback reference passed to ``on()``
+        """
+        listeners = self._events.get(event)
+        if listeners:
+            listeners.discard(callback)
+            if not listeners:
+                del self._events[event]
+
+    def once(self, event, callback):
+        """
+        Subscribe to an event exactly once — auto-unsubscribes after
+        the first call.
+
+        Args:
+            event: Event name
+            callback: Function to call once
+
+        Returns:
+            An unsubscribe function (no-op after first call).
+        """
+        def wrapper(data=None):
+            self.off(event, wrapper)
+            callback(data)
+
+        return self.on(event, wrapper)
+
+    # ------------------------------------------------------------------
+    # Emit
+    # ------------------------------------------------------------------
+
+    def emit(self, event, data=None):
+        """
+        Emit an event to all subscribers.
+
+        Subscribers run synchronously in the caller's greenlet.  If a
+        subscriber raises, the error is logged and remaining subscribers
+        still execute.
+
+        Args:
+            event: Event name
+            data: Optional payload passed to every listener
+        """
+        listeners = self._events.get(event)
+        if not listeners:
+            return
+        # Iterate over a snapshot so subscribers can unsub during iteration
+        for callback in list(listeners):
+            try:
+                callback(data)
+            except Exception as e:
+                logger.error(
+                    f"[SPECTER:bus] Error in listener for '{event}': {e}",
+                    exc_info=True,
+                )
+
+    # ------------------------------------------------------------------
+    # Housekeeping
+    # ------------------------------------------------------------------
+
+    def clear(self, event=None):
+        """
+        Clear listeners.
+
+        Args:
+            event: If provided, clear only listeners for this event.
+                   If ``None``, clear **all** events.
+        """
+        if event:
+            self._events.pop(event, None)
+        else:
+            self._events.clear()
+
+    def has_listeners(self, event):
+        """Return ``True`` if the event has at least one subscriber."""
+        return bool(self._events.get(event))
+
+    def listener_count(self, event=None):
+        """
+        Return listener count.
+
+        Args:
+            event: If provided, count for that event only.
+                   If ``None``, count all listeners across all events.
+        """
+        if event:
+            return len(self._events.get(event, set()))
+        return sum(len(s) for s in self._events.values())
+
+
+# Singleton — the one bus to rule them all.
+bus = EventBus()

specter/core/cache.py

@@ -0,0 +1,301 @@
+# Copyright 2026 BleedingXiko
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""
+SPECTER Cache — Shared state with TTL and dependency-based invalidation.
+
+Shared state with TTL expiry, gevent-safe locking, and automatic cache
+cascade through the bus.
+
+Dependency cascade:
+    When a cache with ``depends_on=['storage:mounts']`` is created, it
+    auto-subscribes to that bus event.  When that event fires, the cache
+    invalidates itself and emits ``'{name}:invalidated'`` on the bus —
+    which in turn triggers any caches that depend on *it*.
+
+    Example chain:
+        storage:mounts  →  drives_cache invalidates
+                            →  emits 'drives:invalidated'
+                                →  categories_cache invalidates
+                                    →  emits 'categories:invalidated'
+                                        →  hidden_files_cache invalidates
+
+Concurrency:
+    All read/write operations are protected by a ``BoundedSemaphore``
+    (gevent-aware).  Never use ``threading.Lock``.
+"""
+
+import time
+import logging
+from gevent.lock import BoundedSemaphore
+
+from .bus import bus
+
+logger = logging.getLogger(__name__)
+
+
+class Cache:
+    """
+    Named cache with TTL and dependency-based cascade invalidation.
+
+    Do not instantiate directly — use :func:`create_cache`.
+    """
+
+    def __init__(self, name, ttl=0, depends_on=None):
+        """
+        Args:
+            name: Unique cache name (used in bus events and logging).
+            ttl: Time-to-live in seconds.  0 means no auto-expiry.
+            depends_on: List of bus event names that trigger invalidation.
+        """
+        self.name = name
+        self._ttl = max(0.0, float(ttl or 0))
+        self._entry_ttl = self._ttl
+        self._value = None
+        self._updated_at = 0
+        self._lock = BoundedSemaphore(1)
+        self._invalidate_callbacks = []
+        self._bus_unsubs = []
+
+        # Subscribe to dependency events
+        if depends_on:
+            for event in depends_on:
+                unsub = bus.on(event, self._on_dependency_invalidated)
+                self._bus_unsubs.append(unsub)
+
+    # ------------------------------------------------------------------
+    # Read
+    # ------------------------------------------------------------------
+
+    def get(self, default=None):
+        """
+        Return cached value, or ``default`` if expired/empty.
+
+        This is a non-blocking read protected by a gevent lock.
+        """
+        with self._lock:
+            if self._value is None:
+                return default
+            if (
+                self._entry_ttl > 0 and
+                (time.time() - self._updated_at) >= self._entry_ttl
+            ):
+                # Expired — clear in place
+                self._value = None
+                self._updated_at = 0
+                self._entry_ttl = self._ttl
+                return default
+            return self._value
+
+    def is_valid(self):
+        """Return ``True`` if the cache has a non-expired value."""
+        with self._lock:
+            if self._value is None:
+                return False
+            if (
+                self._entry_ttl > 0 and
+                (time.time() - self._updated_at) >= self._entry_ttl
+            ):
+                return False
+            return True
+
+    @property
+    def updated_at(self):
+        """Timestamp of the last ``set()`` call (epoch seconds)."""
+        return self._updated_at
+
+    @property
+    def ttl(self):
+        """Configured TTL in seconds.  0 means no auto-expiry."""
+        return self._ttl
+
+    # ------------------------------------------------------------------
+    # Write
+    # ------------------------------------------------------------------
+
+    def set(self, value, ttl=None):
+        """
+        Set the cached value.
+
+        Args:
+            value: The value to cache.
+            ttl: Optional TTL override for this specific write.
+                 Does not change the cache's default TTL.
+        """
+        with self._lock:
+            self._value = value
+            self._updated_at = time.time()
+            self._entry_ttl = self._ttl if ttl is None else max(0.0, float(ttl))
+
+    def get_or_compute(self, factory, ttl=None):
+        """
+        Return cached value if valid, otherwise compute it using
+        ``factory()`` and cache the result.
+
+        This is atomic — only one greenlet runs the factory at a time.
+
+        Args:
+            factory: Callable that returns the value to cache.
+            ttl: Optional TTL override.
+
+        Returns:
+            The cached or freshly computed value.
+        """
+        # Fast path: check without lock contention
+        value = self.get()
+        if value is not None:
+            return value
+
+        # Slow path: compute under lock
+        with self._lock:
+            # Double-check after acquiring lock
+            if self._value is not None:
+                if (
+                    self._entry_ttl == 0 or
+                    (time.time() - self._updated_at) < self._entry_ttl
+                ):
+                    return self._value
+
+            computed = factory()
+            self._value = computed
+            self._updated_at = time.time()
+            self._entry_ttl = self._ttl if ttl is None else max(0.0, float(ttl))
+            return computed
+
+    # ------------------------------------------------------------------
+    # Invalidation
+    # ------------------------------------------------------------------
+
+    def invalidate(self):
+        """
+        Clear the cache and emit ``'{name}:invalidated'`` on the bus.
+
+        Any caches that ``depend_on`` this event will cascade-invalidate.
+        Also fires registered ``on_invalidate`` callbacks.
+        """
+        with self._lock:
+            was_valid = self._value is not None
+            self._value = None
+            self._updated_at = 0
+            self._entry_ttl = self._ttl
+
+        if was_valid:
+            logger.info(f"[SPECTER:cache] '{self.name}' invalidated")
+
+        # Fire invalidation callbacks
+        for cb in list(self._invalidate_callbacks):
+            try:
+                cb()
+            except Exception as e:
+                logger.error(
+                    f"[SPECTER:cache] Error in invalidation callback "
+                    f"for '{self.name}': {e}",
+                    exc_info=True,
+                )
+
+        # Cascade: emit so dependent caches can react
+        bus.emit(f'{self.name}:invalidated')
+
+    def on_invalidate(self, callback):
+        """
+        Subscribe to invalidation events for this cache.
+
+        Args:
+            callback: Callable (no arguments) invoked when the cache
+                      is invalidated.
+
+        Returns:
+            An unsubscribe function.
+        """
+        self._invalidate_callbacks.append(callback)
+        return lambda: (
+            self._invalidate_callbacks.remove(callback)
+            if callback in self._invalidate_callbacks else None
+        )
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def destroy(self):
+        """
+        Tear down the cache: unsubscribe from all bus events,
+        clear callbacks, and reset state.  Called by the framework
+        when the owning service stops.
+        """
+        for unsub in self._bus_unsubs:
+            try:
+                unsub()
+            except Exception:
+                pass
+        self._bus_unsubs.clear()
+        self._invalidate_callbacks.clear()
+        with self._lock:
+            self._value = None
+            self._updated_at = 0
+            self._entry_ttl = self._ttl
+        logger.debug(f"[SPECTER:cache] '{self.name}' destroyed")
+
+    # ------------------------------------------------------------------
+    # Internal
+    # ------------------------------------------------------------------
+
+    def _on_dependency_invalidated(self, data=None):
+        """Bus callback: a dependency was invalidated, so we invalidate too."""
+        logger.debug(
+            f"[SPECTER:cache] '{self.name}' dependency triggered, invalidating"
+        )
+        self.invalidate()
+
+    def __repr__(self):
+        valid = self.is_valid()
+        return (
+            f"<Cache '{self.name}' valid={valid} "
+            f"ttl={self._ttl}s>"
+        )
+
+
+def create_cache(name, ttl=0, depends_on=None):
+    """
+    Factory for creating a named cache.
+
+    Args:
+        name: Unique cache name.
+        ttl: Time-to-live in seconds.  ``0`` = no auto-expiry.
+        depends_on: List of bus event names that trigger invalidation.
+                    Convention: ``'{cache_name}:invalidated'``
+                    or domain events like ``'storage:mounts'``.
+
+    Returns:
+        A :class:`Cache` instance.
+
+    Example::
+
+        category_cache = create_cache(
+            'categories',
+            ttl=86400,
+            depends_on=['storage:mounts'],
+        )
+
+        # Set
+        category_cache.set(categories_list)
+
+        # Get (returns None if expired)
+        cached = category_cache.get()
+
+        # Auto-invalidates when 'storage:mounts' fires on the bus
+    """
+    if depends_on is None:
+        depends_on = []
+    return Cache(name=name, ttl=ttl, depends_on=depends_on)