quantum-framework 0.18.0__py3-none-any.whl

quantum/runtime/websocket_transport.py

@@ -0,0 +1,289 @@
+"""
+The websocket transport that q:websocket never had.
+
+Before this, `quantum/runtime/websocket_service.py` was pure bookkeeping: it
+created a connection record in state CONNECTING, nothing ever moved it to
+OPEN, and send_message — which only queues when the state is OPEN — always
+returned False into a list nothing drained. The tag returned a
+connection-shaped dict for a connection that did not exist.
+
+This opens real client connections with the `websockets` library, on a
+background asyncio loop, and drives the state machine and the handlers the
+service already defines. It is deliberately a CLIENT transport: `q:websocket
+url="wss://..."` connects a Quantum app to somewhere else, which is what the
+tag's url= attribute always meant.
+
+Optional by design: if `websockets` is not installed the service keeps its
+honest stub behaviour and says so, rather than failing to import.
+"""
+
+import asyncio
+import json
+import logging
+import threading
+from concurrent.futures import ThreadPoolExecutor
+from typing import Any, Callable, Dict, Optional
+
+logger = logging.getLogger('quantum.websocket')
+
+try:
+    import websockets as _ws
+    HAS_WEBSOCKETS = True
+except ImportError:            # pragma: no cover - environment dependent
+    _ws = None
+    HAS_WEBSOCKETS = False
+
+
+class WebSocketTransport:
+    """Owns one background event loop and the live client connections on it."""
+
+    def __init__(self):
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._thread: Optional[threading.Thread] = None
+        self._sockets: Dict[str, Any] = {}      # connection id -> protocol
+        self._lock = threading.RLock()
+        # q:websocket handlers are Quantum bodies: they run a component
+        # context and can block for a while. Running them on the event loop
+        # would stall every other connection, so they go to a worker thread.
+        #
+        # UM executor POR CONEXAO, com um unico worker cada.
+        #
+        # Era um executor unico com max_workers=1 para o transporte inteiro,
+        # justificado por "one, so message order is preserved". A ordem por
+        # conexao esta certa; o alcance nao estava. Com um so worker, um
+        # handler on-message lento de UMA conexao segurava a fila de TODAS —
+        # dez conexoes, e um <q:query> de 2s numa delas atrasava as outras
+        # nove em 2s cada. Nada em q:websocket ordena mensagens de conexoes
+        # diferentes entre si, entao nao ha ordem a preservar ali.
+        #
+        # Um worker por conexao mantem a ordem onde ela existe e isola as
+        # conexoes umas das outras.
+        self._dispatchers: Dict[str, ThreadPoolExecutor] = {}
+        self._closed = False
+
+    def _dispatcher_for(self, conn_id: str) -> Optional[ThreadPoolExecutor]:
+        with self._lock:
+            pool = self._dispatchers.get(conn_id)
+            if pool is not None:
+                # Um worker que JA existe continua aceitando trabalho mesmo
+                # durante o shutdown: e por ele que passa o on_close de cada
+                # conexao sendo fechada. Recusar aqui faria o corpo
+                # `on-close` do app nunca rodar num encerramento — que e
+                # justamente quando ele importa.
+                return pool
+            if self._closed:
+                return None
+            pool = ThreadPoolExecutor(
+                max_workers=1,
+                thread_name_prefix=f'quantum-ws-{conn_id[:8]}')
+            self._dispatchers[conn_id] = pool
+            return pool
+
+    def _fire(self, conn_id: str, fn: Callable, *args) -> None:
+        """Run a user handler off the event loop, never letting it escape."""
+        def guarded():
+            try:
+                fn(*args)
+            except Exception:
+                logger.exception("q:websocket handler raised")
+
+        pool = self._dispatcher_for(conn_id)
+        if pool is None:
+            return
+        try:
+            pool.submit(guarded)
+        except RuntimeError:      # pool already shut down
+            pass
+
+    # -- loop lifecycle ----------------------------------------------------
+
+    def _ensure_loop(self) -> asyncio.AbstractEventLoop:
+        with self._lock:
+            # Um shutdown() nao pode aposentar o transporte: get_transport()
+            # devolve um singleton de processo, e reconectar depois de fechar
+            # tudo e uso normal.
+            self._closed = False
+            if self._loop and self._loop.is_running():
+                return self._loop
+            self._loop = asyncio.new_event_loop()
+
+            def run():
+                asyncio.set_event_loop(self._loop)
+                self._loop.run_forever()
+
+            self._thread = threading.Thread(
+                target=run, name="quantum-websocket", daemon=True)
+            self._thread.start()
+            return self._loop
+
+    def shutdown(self) -> None:
+        # As conexoes sao fechadas FORA do lock.
+        #
+        # Antes o laco inteiro rodava com self._lock preso. close() espera o
+        # `sock.close()` terminar no event loop — e o pump() daquela conexao,
+        # ao terminar, faz `with self._lock` no finally, na thread do loop.
+        # Com o lock preso aqui, o loop parava no finally, `sock.close()`
+        # nunca completava, e cada close() gastava os 5s inteiros do timeout
+        # antes de desistir. Cinco conexoes abertas = 25 segundos de shutdown.
+        with self._lock:
+            self._closed = True
+            conn_ids = list(self._sockets)
+
+        # Fechar PRIMEIRO, com os workers ainda vivos: o on_close de cada
+        # conexao roda no worker dela, e o pump, ao terminar, aposenta esse
+        # worker sozinho. Recolher os executores antes deixaria o corpo
+        # `on-close` do app sem ninguem para executa-lo.
+        for conn_id in conn_ids:
+            self.close(conn_id)
+
+        with self._lock:
+            if self._loop and self._loop.is_running():
+                self._loop.call_soon_threadsafe(self._loop.stop)
+            self._loop = None
+            self._thread = None
+            restantes = list(self._dispatchers.values())
+            self._dispatchers.clear()
+
+        # E os workers de handler tambem morrem. Ficavam vivos para sempre:
+        # cada reset_transport() em teste deixava mais uma thread
+        # 'quantum-ws-handler' parada no processo, e um app que fechasse suas
+        # conexoes nunca recuperava a thread.
+        for pool in restantes:
+            pool.shutdown(wait=False)
+
+    # -- connecting --------------------------------------------------------
+
+    def connect(
+        self,
+        conn_id: str,
+        url: str,
+        on_open: Callable[[], None],
+        on_message: Callable[[Any], None],
+        on_close: Callable[[], None],
+        on_error: Callable[[Exception], None],
+        timeout: float = 10.0,
+    ):
+        """Open a real connection. Returns (ok, error).
+
+        Blocks up to `timeout` so q:websocket can report a truthful state
+        instead of leaving the caller with a record that says CONNECTING
+        forever — and returns the failure reason with the answer, because
+        the on_error callback lands on the handler thread later and the
+        caller needs it now.
+        """
+        if not HAS_WEBSOCKETS:
+            logger.warning(
+                "q:websocket needs the 'websockets' package to open a real "
+                "connection (pip install websockets). Leaving %s unconnected.",
+                url
+            )
+            return False, "the 'websockets' package is not installed"
+
+        loop = self._ensure_loop()
+        opened = threading.Event()
+        result = {'ok': False, 'error': None}
+
+        async def pump():
+            try:
+                async with _ws.connect(url, open_timeout=timeout) as sock:
+                    with self._lock:
+                        self._sockets[conn_id] = sock
+                    result['ok'] = True
+                    opened.set()
+                    self._fire(conn_id, on_open)
+                    async for raw in sock:
+                        # JSON when it parses, raw text otherwise — the same
+                        # rule the send side uses.
+                        try:
+                            payload = json.loads(raw)
+                        except (ValueError, TypeError):
+                            payload = raw
+                        self._fire(conn_id, on_message, payload)
+            except Exception as exc:
+                result['error'] = exc
+                opened.set()
+                self._fire(conn_id, on_error, exc)
+            finally:
+                with self._lock:
+                    self._sockets.pop(conn_id, None)
+                self._fire(conn_id, on_close)
+                # O worker desta conexao acaba com ela. shutdown(wait=False)
+                # nao cancela o que ja foi submetido, entao o on_close acima
+                # ainda roda; so nao fica uma thread parada por conexao ja
+                # encerrada.
+                with self._lock:
+                    pool = self._dispatchers.pop(conn_id, None)
+                if pool is not None:
+                    pool.shutdown(wait=False)
+
+        asyncio.run_coroutine_threadsafe(pump(), loop)
+        if not opened.wait(timeout=timeout + 1):
+            logger.warning("q:websocket: connecting to %s timed out", url)
+            return False, f"connection to {url} timed out"
+
+        if result['error'] is not None:
+            logger.warning("q:websocket could not connect to %s: %s",
+                           url, result['error'])
+            return False, str(result['error']) or type(result['error']).__name__
+        return bool(result['ok']), None
+
+    # -- sending -----------------------------------------------------------
+
+    def send(self, conn_id: str, data: Any, timeout: float = 5.0) -> bool:
+        """Actually transmit. Returns True only when the frame was written."""
+        with self._lock:
+            sock = self._sockets.get(conn_id)
+        if sock is None or self._loop is None:
+            return False
+
+        payload = data if isinstance(data, (str, bytes)) else json.dumps(
+            data, default=str)
+        fut = asyncio.run_coroutine_threadsafe(sock.send(payload), self._loop)
+        try:
+            fut.result(timeout=timeout)
+            return True
+        except Exception as exc:
+            logger.warning("q:websocket send failed on %s: %s", conn_id, exc)
+            return False
+
+    # -- closing -----------------------------------------------------------
+
+    def close(self, conn_id: str, timeout: float = 5.0) -> bool:
+        with self._lock:
+            sock = self._sockets.get(conn_id)
+        if sock is None or self._loop is None:
+            return False
+        fut = asyncio.run_coroutine_threadsafe(sock.close(), self._loop)
+        try:
+            fut.result(timeout=timeout)
+        except Exception:
+            pass
+        with self._lock:
+            self._sockets.pop(conn_id, None)
+        return True
+
+    def is_open(self, conn_id: str) -> bool:
+        with self._lock:
+            return conn_id in self._sockets
+
+
+_transport: Optional[WebSocketTransport] = None
+_transport_lock = threading.Lock()
+
+
+def get_transport() -> WebSocketTransport:
+    """The process-wide transport (one event loop for every connection)."""
+    global _transport
+    with _transport_lock:
+        if _transport is None:
+            _transport = WebSocketTransport()
+        return _transport
+
+
+def reset_transport() -> None:
+    """Drop the transport, closing whatever it holds (tests)."""
+    global _transport
+    with _transport_lock:
+        if _transport is not None:
+            _transport.shutdown()
+        _transport = None

quantum/runtime/wsgi.py

@@ -0,0 +1,101 @@
+"""
+Quantum WSGI Entry Point
+
+Factory for creating Flask app instances for Gunicorn deployment.
+Loads configuration from environment or config file.
+"""
+
+import os
+import sys
+from pathlib import Path
+
+# Ensure src directory is in path
+
+from quantum.runtime.web_server import QuantumWebServer
+
+
+def _run_app_startup():
+    """
+    Run app-specific startup.py if present.
+
+    This allows apps to initialize databases, apply runtime patches,
+    and perform other setup before the web server starts.
+    The startup module should define a run() function.
+
+    Note that this executes a Python file from `/app` or from the CURRENT
+    DIRECTORY, and that `app = create_app()` at the bottom of this module
+    runs it at IMPORT time. Importing this module therefore executes the
+    working directory's startup.py. That is the documented Docker convention
+    and it is kept, but it is loud now: silently executing a file because it
+    happens to sit in the directory you launched from is the kind of thing
+    that should say so.
+    """
+    startup_path = Path('/app/startup.py')
+    if not startup_path.exists():
+        # Also check current working directory
+        startup_path = Path('startup.py')
+    if startup_path.exists():
+        print(f"[WSGI] executing {startup_path.resolve()}", flush=True)
+        import importlib.util
+        spec = importlib.util.spec_from_file_location('app_startup', str(startup_path))
+        mod = importlib.util.module_from_spec(spec)
+        spec.loader.exec_module(mod)
+        if hasattr(mod, 'run'):
+            mod.run()
+            print("[WSGI] App startup.py executed", flush=True)
+
+
+def create_app(config_path: str = None) -> 'Flask':
+    """
+    Create and configure the Quantum Flask application.
+
+    This is the factory function used by Gunicorn.
+
+    Args:
+        config_path: Path to quantum.config.yaml. If not provided,
+                     uses QUANTUM_CONFIG env var or default path.
+
+    Returns:
+        Configured Flask application instance
+    """
+    # Run app startup hooks before creating the server
+    _run_app_startup()
+
+    # Determine config path
+    if config_path is None:
+        config_path = os.environ.get('QUANTUM_CONFIG', '/app/quantum.config.yaml')
+
+    # Check for app-specific config first
+    if os.path.exists(config_path):
+        server = QuantumWebServer(config_path)
+    else:
+        # Fall back to default config
+        server = QuantumWebServer()
+
+    return server.app
+
+
+# Create app instance for Gunicorn
+#
+# Usage: gunicorn "quantum.runtime.wsgi:app"
+#
+# This said `src.runtime.wsgi:app` — the layout that stopped existing when
+# `src/` became the `quantum/` package. The command in the one file whose
+# entire purpose is being that command did not import. (web_server.py's
+# docstring had the same defect; this file was missed.)
+app = create_app()
+
+
+# Also support: gunicorn "quantum.runtime.wsgi:create_app()"
+def get_app():
+    """Alternative factory for Gunicorn."""
+    return create_app()
+
+
+if __name__ == '__main__':
+    # For local testing
+    app.run(
+        host=os.environ.get('QUANTUM_HOST', '0.0.0.0'),
+        port=int(os.environ.get('QUANTUM_PORT', 8080)),
+        debug=os.environ.get('QUANTUM_DEBUG', 'false').lower() == 'true'
+    )

quantum/services.py

@@ -0,0 +1,109 @@
+"""
+Declared services: Python functions a .q file calls by name (SVC-1..3).
+
+    # myapp/services.py
+    from quantum.services import service
+
+    @service("projects.list")
+    def list_projects(status: str = "active"):
+        return [...]
+
+    # quantum.config.yaml
+    services:
+      - myapp.services
+
+    <!-- components/projects.q -->
+    <q:invoke name="projects" service="projects.list">
+      <q:param name="status" value="active" />
+    </q:invoke>
+
+This is the alternative to <q:python> for logic that belongs in Python — file
+system, processes, third-party APIs. The Python is written, reviewed and tested
+as ordinary Python; the page only names what it calls. A module runs only when
+quantum.config.yaml lists it: nothing is discovered or imported implicitly.
+"""
+
+import importlib
+import threading
+from typing import Any, Callable, Dict, Iterable
+
+_registry: Dict[str, Callable[..., Any]] = {}
+_loaded_modules: set = set()
+_lock = threading.Lock()
+
+
+class ServiceError(Exception):
+    """A declared service could not be registered, loaded or found."""
+
+
+def service(name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Register a function under `name` (SVC-1). Returns the function unchanged."""
+    if not isinstance(name, str) or not name.strip():
+        raise ServiceError("@service needs a name, like @service('projects.list')")
+
+    def register(func: Callable[..., Any]) -> Callable[..., Any]:
+        with _lock:
+            existing = _registry.get(name)
+            if existing is not None and existing is not func and \
+                    (existing.__module__, existing.__qualname__) != (func.__module__, func.__qualname__):
+                raise ServiceError(
+                    f"service '{name}' is already registered by "
+                    f"{existing.__module__}.{existing.__qualname__}")
+            _registry[name] = func
+        return func
+
+    return register
+
+
+def load(modules: Iterable[str], project_dir: str = None) -> None:
+    """Import the modules listed under `services:` in quantum.config.yaml (SVC-2).
+
+    The project folder goes on sys.path first: the `quantum` console script,
+    unlike `python -m`, does not put the current directory there, so
+    `services: [myapp.services]` could not be imported by `quantum start`.
+    """
+    import os
+    import sys
+    if isinstance(modules, str):
+        modules = [modules]
+    raiz = os.path.abspath(project_dir or os.getcwd())
+    if modules and raiz not in sys.path:
+        sys.path.insert(0, raiz)
+    for module in modules or []:
+        if module in _loaded_modules:
+            continue
+        try:
+            ja_importado = module in sys.modules
+            modulo = importlib.import_module(module)
+            if ja_importado and not any(f.__module__ == module for f in _registry.values()):
+                # Imported before the registry was cleared (or before it
+                # existed): its @service decorators already ran and would not
+                # run again on a plain import.
+                importlib.reload(modulo)
+        except ImportError as exc:
+            raise ServiceError(
+                f"quantum.config.yaml lists service module '{module}', which could not "
+                f"be imported: {exc}") from exc
+        _loaded_modules.add(module)
+
+
+def get(name: str) -> Callable[..., Any]:
+    """The function registered as `name`, or an error listing what exists (SVC-3)."""
+    func = _registry.get(name)
+    if func is None:
+        disponiveis = ', '.join(sorted(_registry)) or 'none'
+        raise ServiceError(
+            f"no service named '{name}' (registered: {disponiveis}). Declare it with "
+            f"@service('{name}') in a module listed under services: in quantum.config.yaml")
+    return func
+
+
+def registered() -> Dict[str, Callable[..., Any]]:
+    return dict(_registry)
+
+
+def _reset() -> None:
+    """Tests only."""
+    with _lock:
+        _registry.clear()
+        _loaded_modules.clear()

quantum/utils/__init__.py

@@ -0,0 +1 @@
+# Utils - placeholder para futuras utilidades

quantum_admin/__init__.py

@@ -0,0 +1,4 @@
+"""Quantum Admin: .q screens (components/admin) over declared services (services/).
+
+Started with `quantum admin`; needs the [admin] extra.
+"""

quantum_admin/assets/quantum-admin-connectors.js

@@ -0,0 +1,123 @@
+/**
+ * Quantum Admin - Connectors Page
+ * Dynamic Provider <-> Type filtering
+ */
+(function () {
+  'use strict';
+
+  var typeProviders = {
+    database: ['postgres', 'mysql', 'mariadb', 'mongodb', 'sqlite', 'influxdb'],
+    mq:       ['rabbitmq', 'redis_queue', 'kafka'],
+    cache:    ['redis', 'memcached'],
+    storage:  ['s3', 'minio', 'local'],
+    ai:       ['ollama', 'lmstudio', 'anthropic', 'openai', 'openrouter']
+  };
+
+  // Build reverse map: provider -> type
+  var providerType = {};
+  Object.keys(typeProviders).forEach(function (type) {
+    typeProviders[type].forEach(function (prov) {
+      providerType[prov] = type;
+    });
+  });
+
+  var typeSelect = document.querySelector('select[name="conn_type"]');
+  var providerSelect = document.querySelector('select[name="provider"]');
+
+  if (!typeSelect || !providerSelect) return;
+
+  // Store original options with their optgroup labels
+  var allOptions = [];
+  var optgroups = providerSelect.querySelectorAll('optgroup');
+  optgroups.forEach(function (og) {
+    var label = og.getAttribute('label') || '';
+    var opts = og.querySelectorAll('option');
+    opts.forEach(function (opt) {
+      allOptions.push({ value: opt.value, text: opt.textContent, group: label });
+    });
+  });
+
+  var syncing = false;
+
+  function rebuildProviderOptions(allowedType) {
+    // Remove everything except the placeholder
+    while (providerSelect.options.length > 1) {
+      providerSelect.remove(1);
+    }
+    // Remove old optgroups
+    var oldGroups = providerSelect.querySelectorAll('optgroup');
+    oldGroups.forEach(function (g) { g.remove(); });
+
+    if (!allowedType) {
+      // Show all grouped
+      var groups = {};
+      allOptions.forEach(function (o) {
+        if (!groups[o.group]) groups[o.group] = [];
+        groups[o.group].push(o);
+      });
+      Object.keys(groups).forEach(function (gName) {
+        var og = document.createElement('optgroup');
+        og.label = gName;
+        groups[gName].forEach(function (o) {
+          var opt = document.createElement('option');
+          opt.value = o.value;
+          opt.textContent = o.text;
+          og.appendChild(opt);
+        });
+        providerSelect.appendChild(og);
+      });
+    } else {
+      // Show only providers for this type, flat (no optgroup)
+      var allowed = typeProviders[allowedType] || [];
+      allOptions.forEach(function (o) {
+        if (allowed.indexOf(o.value) !== -1) {
+          var opt = document.createElement('option');
+          opt.value = o.value;
+          opt.textContent = o.text;
+          providerSelect.appendChild(opt);
+        }
+      });
+    }
+  }
+
+  typeSelect.addEventListener('change', function () {
+    if (syncing) return;
+    syncing = true;
+    var selectedType = typeSelect.value;
+    var currentProvider = providerSelect.value;
+    rebuildProviderOptions(selectedType);
+
+    // Try to keep current provider if it belongs to the new type
+    if (currentProvider) {
+      var allowed = typeProviders[selectedType] || [];
+      if (allowed.indexOf(currentProvider) !== -1) {
+        providerSelect.value = currentProvider;
+      } else {
+        providerSelect.value = '';
+      }
+    }
+    syncing = false;
+  });
+
+  providerSelect.addEventListener('change', function () {
+    if (syncing) return;
+    syncing = true;
+    var prov = providerSelect.value;
+    if (prov && providerType[prov]) {
+      typeSelect.value = providerType[prov];
+      // Also filter providers to match the auto-selected type
+      rebuildProviderOptions(providerType[prov]);
+      providerSelect.value = prov;
+    }
+    syncing = false;
+  });
+
+  // On load: if type is pre-selected (edit mode), filter providers
+  if (typeSelect.value) {
+    var editProvider = providerSelect.value;
+    rebuildProviderOptions(typeSelect.value);
+    if (editProvider) {
+      providerSelect.value = editProvider;
+    }
+  }
+})();