quantum-framework 0.9.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/utils/__init__.py

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

quantum_framework-0.9.0.dist-info/METADATA

@@ -0,0 +1,244 @@
+Metadata-Version: 2.4
+Name: quantum-framework
+Version: 0.9.0
+Summary: Full-stack declarative framework for building web, desktop, and mobile applications
+Author-email: Daniel Gregorio <danielgregorio2611@gmail.com>
+License: MIT
+Project-URL: Homepage, https://quantum.sargas.cloud
+Project-URL: Documentation, https://quantum.sargas.cloud
+Project-URL: Repository, https://github.com/danielgregorio/quantum
+Keywords: framework,declarative,xml,web,desktop,mobile
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Flask
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: flask>=3.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: sqlparse>=0.4.4
+Requires-Dist: gunicorn>=21.0.0
+Requires-Dist: textual>=0.80.0
+Requires-Dist: requests>=2.31.0
+Requires-Dist: bcrypt>=4.1.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.11.1; extra == "dev"
+Requires-Dist: black>=23.0.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Provides-Extra: db
+Requires-Dist: psycopg2-binary>=2.9.9; extra == "db"
+Requires-Dist: pymysql>=1.1.0; extra == "db"
+Provides-Extra: rag
+Requires-Dist: chromadb>=0.5.0; extra == "rag"
+Provides-Extra: jobs
+Requires-Dist: apscheduler>=3.10.0; extra == "jobs"
+Provides-Extra: websocket
+Requires-Dist: websockets>=12.0; extra == "websocket"
+Dynamic: license-file
+
+# Quantum
+
+[![CI](https://github.com/danielgregorio/quantum/actions/workflows/ci.yml/badge.svg)](https://github.com/danielgregorio/quantum/actions/workflows/ci.yml)
+[![Docker](https://github.com/danielgregorio/quantum/actions/workflows/docker.yml/badge.svg)](https://github.com/danielgregorio/quantum/actions/workflows/docker.yml)
+[![Docs](https://img.shields.io/badge/docs-github.io-blue)](https://danielgregorio.github.io/quantum/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+> **Declarative web apps in XML, with AI and RAG built into the language.
+> No build chain, no JavaScript, no frontend framework.**
+
+Quantum is a full-stack framework whose language is markup. State, database queries,
+forms, LLM calls and retrieval-augmented generation are all tags — not libraries you
+wire together. It takes its philosophy from ColdFusion and Adobe Flex: the markup *is*
+the app.
+
+> ⚠️ **Pre-1.0, and honest about it.** See [Stability](#stability) — the table there
+> reflects what has actually been executed end-to-end, not what is aspirational.
+
+---
+
+## The part that isn't like the others
+
+Retrieval-augmented generation, as a language construct:
+
+```xml
+<q:component name="DocsBot">
+  <q:knowledge name="docs" model="phi3" embedModel="nomic-embed-text">
+    <q:source type="directory" path="./docs/" pattern="*.md" />
+  </q:knowledge>
+
+  <q:query name="answer" datasource="knowledge:docs" mode="rag">
+    SELECT answer FROM chunks WHERE content SIMILAR TO :question
+    <q:param name="question" value="{form.question}" type="string" />
+  </q:query>
+
+  <p>{answer.answer}</p>
+</q:component>
+```
+
+That indexes a directory, embeds it, stores the vectors, retrieves the relevant chunks
+and asks the model — in the markup. There is no Python file behind it.
+
+An agent with its own tools, same idea:
+
+```xml
+<q:agent name="calc" model="phi3" max_iterations="4">
+  <q:instruction>Use the add tool, then answer.</q:instruction>
+
+  <q:tool name="add" description="Add two numbers">
+    <q:param name="a" type="number" required="true" />
+    <q:param name="b" type="number" required="true" />
+    <q:function name="doAdd">
+      <q:set name="sum" value="{a + b}" type="number" />
+      <q:return value="{sum}" />
+    </q:function>
+  </q:tool>
+
+  <q:execute task="What is 17 plus 25?" />
+</q:agent>
+```
+
+The tool body is Quantum, not Python. The reasoning loop, the tool call and the type
+coercion of the model's arguments are the runtime's job.
+
+---
+
+## The rest of the language
+
+```xml
+<q:component name="Orders">
+  <q:query name="orders" datasource="db">
+    SELECT id, customer, total FROM orders WHERE total > :min
+    <q:param name="min" value="100" type="decimal" />
+  </q:query>
+
+  <table>
+    <q:loop query="orders">
+      <tr><td>{orders.customer}</td><td>{orders.total}</td></tr>
+    </q:loop>
+  </table>
+</q:component>
+```
+
+`q:query` refuses to run SQL with an undeclared `:param` — parameterised queries are
+enforced by the parser, not by discipline.
+
+Also core: `q:set` with `session.` / `application.` / `request.` scopes, `q:if`,
+`q:function`, `q:action` for form handling, `q:data` for CSV/JSON/XML import,
+`q:import` / `q:slot` for composition.
+
+---
+
+## Quick start
+
+**Requirements:** Python 3.11+ and `pip`.
+
+```bash
+git clone https://github.com/danielgregorio/quantum.git
+cd quantum
+pip install -e ".[dev]"
+
+quantum run examples/hello.q
+```
+
+```
+[EXEC] Executing component: HelloWorld
+[SUCCESS] Result: Hello World!
+```
+
+For the AI examples you also need an [Ollama](https://ollama.com) server and the RAG
+extra:
+
+```bash
+pip install -e ".[rag]"
+ollama pull phi3 && ollama pull nomic-embed-text
+export QUANTUM_LLM_BASE_URL=http://localhost:11434
+```
+
+Declare datasources in `quantum.config.yaml` and `q:query` works with nothing else
+running:
+
+```yaml
+datasources:
+  db:
+    driver: sqlite
+    database: ./data/app.db
+```
+
+### CLI
+
+| Command | What it does |
+|---------|--------------|
+| `run <file.q>` | Execute a component, app, or API |
+| `start` | Start the web server |
+| `deploy <dir>` | Deploy an application |
+| `pkg` · `jobs` · `mq` · `migrate` | Packages, jobs, message queues, migrations |
+
+---
+
+## Documentation
+
+Full docs (VitePress) at **[danielgregorio.github.io/quantum](https://danielgregorio.github.io/quantum/)** and in
+[`docs/`](docs/):
+
+- [Getting Started](docs/guide/getting-started.md) · [Installation](docs/guide/installation.md) · [Quick Start](docs/guide/quick-start.md)
+- [Components](docs/guide/components.md) · [State](docs/guide/state-management.md) · [Loops](docs/guide/loops.md) · [Conditionals](docs/guide/conditionals.md)
+- [Queries](docs/guide/query.md) · [Functions](docs/guide/functions.md) · [Data fetching](docs/guide/data-fetching.md)
+
+---
+
+## Stability
+
+Support levels are defined in **[SUPPORT_TIERS.md](SUPPORT_TIERS.md)**. Short version:
+
+| Surface | Status |
+|---------|--------|
+| Core language — `q:component`, `q:set`, `q:if`, `q:loop`, `q:function`, `q:query`, `q:action`, `q:invoke`, `q:data` | **Stable** |
+| AI — `q:llm`, `q:knowledge`, `q:agent` | **Beta** — validated end-to-end against a live Ollama server |
+| `q:team` (multi-agent handoff) | Beta, less exercised |
+| Jobs, messaging, websockets, mail, file uploads, `ui:*`, terminal target | **Experimental** — they run, but no API stability promise |
+| Python scripting (`q:python`, `q:pyclass`, `q:pyimport`) | Experimental, and a full-trust escape hatch — see [SECURITY.md](SECURITY.md) |
+
+A functional audit in 2026-09 found that several of these surfaces had never been run
+end-to-end despite being documented as complete. The findings and the fixes are in
+[`FULL_AUDIT_2026-09.md`](FULL_AUDIT_2026-09.md) and
+[`AUDIT_FIX_PLAN.md`](AUDIT_FIX_PLAN.md). Feature status is now verified by execution
+rather than asserted by hand.
+
+Pre-1.0: APIs may change between minor versions.
+
+---
+
+## Project layout
+
+```
+quantum/
+├── quantum/
+│   ├── core/        # Parser & AST (registry-based, modular)
+│   ├── runtime/     # Execution engine, web server, renderer
+│   └── cli/         # Command-line entry point
+├── examples/        # runnable .q examples
+├── tests/           # pytest suite (~2.4k tests)
+├── scripts/         # dev tools
+└── docs/            # VitePress documentation
+```
+
+Adding a tag is one parser + one executor + a registry entry — see
+[CONTRIBUTING.md](CONTRIBUTING.md).
+
+---
+
+## Contributing
+
+Read **[CONTRIBUTING.md](CONTRIBUTING.md)** for dev setup and how the modular
+parser/executor architecture works. By participating you agree to the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
+Found a security issue? Follow [SECURITY.md](SECURITY.md) — **do not** open a public issue.
+
+## License
+
+MIT — see [LICENSE](LICENSE).