fixtureqa 0.1.0__tar.gz

fixtureqa-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aidan Chisholm
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fixtureqa-0.1.0/PKG-INFO

@@ -0,0 +1,16 @@
+Metadata-Version: 2.4
+Name: fixtureqa
+Version: 0.1.0
+Summary: FIXture — FIX Protocol Testing Tool
+Requires-Python: >=3.10
+License-File: LICENSE
+Requires-Dist: fixcore-engine
+Requires-Dist: fastapi>=0.111.0
+Requires-Dist: uvicorn[standard]>=0.29.0
+Requires-Dist: websockets>=12.0
+Requires-Dist: python-jose[cryptography]>=3.3.0
+Requires-Dist: passlib[bcrypt]>=1.7.4
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: httpx; extra == "dev"
+Dynamic: license-file

fixtureqa-0.1.0/README.md

@@ -0,0 +1,96 @@
+# FIXture
+
+A Python FIX protocol testing tool. Supports FIX 4.2 and 4.4, dynamic session creation at runtime (no restart required), and both initiator and acceptor roles per session.
+
+![FIXture](frontend/src/assets/logo-dark.svg)
+
+---
+
+## Features
+
+- **FIX 4.2 and 4.4** support with bundled data dictionaries
+- **Initiator and acceptor** roles, configurable per session
+- **Dynamic sessions** — add or remove sessions without restarting
+- **Multi-user auth** — JWT login, per-user session isolation, admin panel
+- **Message log** — real-time IN/OUT stream with field breakdown, filtering, cursor pagination
+- **Compose & send** — paste raw FIX or use message templates; auto-inject tag 60 and primary ID
+- **Templates** — create/edit reusable message templates with FIX spec field definitions
+- **Scenarios** — automated send/expect/delay test scripts with live pass/fail results
+- **Venue simulation** — auto-ack and auto-fill responses for inbound NewOrderSingles
+- **Log analysis** — Overview stats, Throughput chart, Reject detail, Latency measurement (p50/p95/p99)
+- **Export** — download session messages as CSV or raw FIX
+- **Sequence numbers** — view and reset TX/RX seqnums per session
+- **Persistent storage** — SQLite message store, per-user session configs, survives restarts
+- **Web UI** — dark/light theme React frontend
+
+## Requirements
+
+- Python 3.10+
+- [quickfix](https://pypi.org/project/quickfix/) 1.15.1
+- Node.js 20+ (frontend dev/build only)
+
+## Quick start — Docker (recommended)
+
+```bash
+docker compose up
+```
+
+Open http://localhost:8000. On first run, the setup page will prompt you to create an admin account.
+
+## Quick start — local
+
+```bash
+# Install Python dependencies
+pip install -e ".[dev]"
+
+# Build the frontend (once, or after UI changes)
+cd frontend && npm install && npm run build && cd ..
+
+# Run
+python -m fixture
+```
+
+Open http://localhost:8000.
+
+## Development
+
+```bash
+./dev.sh   # activates .venv, starts backend (:8000) + Vite dev server (:5173)
+```
+
+Frontend dev server runs at http://localhost:5173 and proxies API/WebSocket calls to `:8000`.
+
+## Options
+
+```
+python -m fixture [--host HOST] [--port PORT] [--log-level LEVEL] [--log-file PATH] [--data-dir PATH] [--db-path PATH]
+```
+
+| Flag | Default | Description |
+|---|---|---|
+| `--host` | `0.0.0.0` | Bind address |
+| `--port` | `8000` | HTTP port |
+| `--log-level` | `info` | Log level (debug/info/warning/error) |
+| `--log-file` | *(none)* | Write rotating log file (10 MB × 5 backups) |
+| `--data-dir` | `./data` | Directory for per-user session configs and message DB |
+| `--db-path` | `./users.db` | SQLite user accounts database |
+
+## Architecture
+
+One QuickFIX engine per session, each running in its own daemon thread. This enables dynamic session creation without restarting.
+
+```
+SessionManager
+  └── Session (one per FIX session)
+        ├── FixApplication  ← QuickFIX callbacks
+        ├── SocketInitiator or SocketAcceptor
+        └── daemon thread
+```
+
+Events flow upward via an observer pattern to the FastAPI WebSocket layer and into the React UI.
+
+## Running tests
+
+```bash
+pytest tests/
+```

fixtureqa-0.1.0/fixture/__init__.py

@@ -0,0 +1,22 @@
+from .core.session_manager import SessionManager
+from .core.models import SessionConfig, SessionState, SessionStatus, ConnectionType
+from .core.events import SessionEvent, EventType
+from .core.message_log import MessageLog, LogEntry
+from .core.fix_parser import parse_raw, pretty_print
+from .core.fix_tags import tag_name, msg_type_name
+
+__all__ = [
+    "SessionManager",
+    "SessionConfig",
+    "SessionState",
+    "SessionStatus",
+    "ConnectionType",
+    "SessionEvent",
+    "EventType",
+    "MessageLog",
+    "LogEntry",
+    "parse_raw",
+    "pretty_print",
+    "tag_name",
+    "msg_type_name",
+]

fixtureqa-0.1.0/fixture/__main__.py

@@ -0,0 +1,161 @@
+"""
+python -m fixture [--host HOST] [--port PORT]
+"""
+
+import argparse
+import json
+import logging
+import logging.handlers
+import os
+import time
+
+from .core.session_manager import SessionManager
+from .core.config_store import ConfigStore
+from .server import start_server
+
+logger = logging.getLogger("fixture")
+
+
+def _configure_logging(level_name: str, log_file: str | None = None) -> None:
+    """
+    Configure the root logger and (optionally) a rotating file handler.
+
+    Passing log_config=None to uvicorn.Config prevents uvicorn from
+    overriding this setup, so uvicorn's own loggers propagate here too.
+    """
+    level = getattr(logging, level_name.upper(), logging.INFO)
+    fmt = "%(asctime)s  %(levelname)-8s  %(name)s — %(message)s"
+    datefmt = "%Y-%m-%d %H:%M:%S"
+    formatter = logging.Formatter(fmt, datefmt)
+
+    root = logging.getLogger()
+    root.setLevel(level)
+
+    # Stdout handler
+    sh = logging.StreamHandler()
+    sh.setFormatter(formatter)
+    root.addHandler(sh)
+
+    # Optional rotating file handler
+    if log_file:
+        fh = logging.handlers.RotatingFileHandler(
+            log_file, maxBytes=10 * 1024 * 1024, backupCount=5, encoding="utf-8"
+        )
+        fh.setFormatter(formatter)
+        root.addHandler(fh)
+
+
+def _migrate_legacy(sessions_file: str, data_dir: str, db_path: str) -> None:
+    """
+    One-time migration: read a legacy sessions.json, group by owner_uid,
+    write to data_dir/<uid>/sessions.json, then rename the legacy file.
+    Sessions with no owner_uid are assigned to the platform_admin.
+    """
+    if not os.path.isfile(sessions_file):
+        return
+
+    # Check if data_dir already has any sessions (migration already done)
+    if os.path.isdir(data_dir) and any(
+        os.path.isfile(os.path.join(data_dir, uid, "sessions.json"))
+        for uid in os.listdir(data_dir)
+        if os.path.isdir(os.path.join(data_dir, uid))
+    ):
+        return
+
+    logger.info("Migrating %s → %s/<uid>/sessions.json ...", sessions_file, data_dir)
+
+    try:
+        with open(sessions_file) as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError) as e:
+        logger.warning("Migration skipped: could not read %s: %s", sessions_file, e)
+        return
+
+    # Find the platform_admin uid to assign orphaned sessions
+    fallback_uid = _get_platform_admin_uid(db_path)
+
+    by_user: dict = {}
+    for entry in data:
+        uid = entry.get("owner_uid") or fallback_uid
+        if not uid:
+            continue
+        # Remove owner_uid from stored JSON (canonical from directory name)
+        entry.pop("owner_uid", None)
+        by_user.setdefault(uid, []).append(entry)
+
+    for uid, entries in by_user.items():
+        user_dir = os.path.join(data_dir, uid)
+        os.makedirs(user_dir, exist_ok=True)
+        path = os.path.join(user_dir, "sessions.json")
+        tmp = path + ".tmp"
+        with open(tmp, "w") as f:
+            json.dump(entries, f, indent=2)
+        os.replace(tmp, path)
+        logger.info("  Wrote %d session(s) for user %s", len(entries), uid)
+
+    migrated = sessions_file + ".migrated"
+    os.rename(sessions_file, migrated)
+    logger.info("Migration complete. Legacy file renamed to %s", migrated)
+
+
+def _get_platform_admin_uid(db_path: str) -> str:
+    """Return the uid of the first platform_admin, or '' if not found."""
+    try:
+        import sqlite3
+        conn = sqlite3.connect(db_path)
+        row = conn.execute(
+            "SELECT uid FROM users WHERE role='platform_admin' ORDER BY created_at LIMIT 1"
+        ).fetchone()
+        conn.close()
+        return row[0] if row else ""
+    except Exception:
+        return ""
+
+
+def main():
+    parser = argparse.ArgumentParser(description="FIXture FIX testing tool")
+    parser.add_argument("--host", default="0.0.0.0")
+    parser.add_argument("--port", type=int, default=8000)
+    parser.add_argument("--log-level", default="info")
+    parser.add_argument("--log-file", default=None,
+                        help="Path for rotating log file (default: <data-dir>/fixture.log)")
+    parser.add_argument("--data-dir", default="./data",
+                        help="Directory for per-user session data")
+    parser.add_argument("--db-path", default="./users.db",
+                        help="Path to SQLite database for user accounts")
+    args = parser.parse_args()
+
+    # Ensure data dir exists before opening the log file inside it
+    os.makedirs(args.data_dir, exist_ok=True)
+
+    # Default log file lives next to the other data files
+    log_file = args.log_file or os.path.join(args.data_dir, "fixture.log")
+
+    # Configure logging before anything else so all modules inherit the setup
+    _configure_logging(args.log_level, log_file)
+
+    # Auto-migrate legacy sessions.json if present
+    _migrate_legacy("./sessions.json", args.data_dir, args.db_path)
+
+    store = ConfigStore(args.data_dir)
+    msg_db_path = os.path.join(args.data_dir, "messages.db")
+    sm = SessionManager(config_store=store, msg_db_path=msg_db_path)
+    sm.load_persisted()
+    server = start_server(sm, host=args.host, port=args.port, log_level=args.log_level,
+                          db_path=args.db_path, msg_db_path=msg_db_path, log_dir="./log",
+                          data_dir=args.data_dir)
+
+    logger.info("FIXture running at http://%s:%s", args.host, args.port)
+
+    try:
+        while not server.should_exit:
+            time.sleep(0.5)
+    except KeyboardInterrupt:
+        pass
+    finally:
+        server.should_exit = True
+        logger.info("Shutting down...")
+
+
+if __name__ == "__main__":
+    main()

fixtureqa-0.1.0/fixture/api/app.py

@@ -0,0 +1,95 @@
+import os
+from contextlib import asynccontextmanager
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from fastapi.responses import FileResponse
+
+from ..core.housekeeping import HousekeepingService
+from ..core.session_manager import SessionManager
+from ..core.scenario_store import ScenarioStore
+from ..core.scenario_runner import ScenarioRunner
+from ..core.template_store import TemplateStore
+from ..core.user_store import UserStore
+from .connection_manager import ConnectionManager
+from .routers import sessions, messages, ws, auth, setup, admin, fix_spec, templates, scenarios, branding
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    # Register event bridge with SessionManager
+    sm: SessionManager = app.state.session_manager
+    cm: ConnectionManager = app.state.connection_manager
+    sm.subscribe(cm.sync_event_handler)
+    # Start background housekeeping thread
+    app.state.housekeeping.start()
+    yield
+    sm.unsubscribe(cm.sync_event_handler)
+    sm.close()  # flush SQLite writer
+
+
+def create_app(
+    session_manager: SessionManager,
+    db_path: str = "./users.db",
+    msg_db_path: str = "./data/messages.db",
+    log_dir: str = "./log",
+    data_dir: str = "./data",
+) -> FastAPI:
+    app = FastAPI(
+        title="FIXture",
+        description="FIX Protocol Testing Tool",
+        version="0.1.0",
+        lifespan=lifespan,
+    )
+
+    # Store singletons on app state (injected via Depends)
+    app.state.session_manager = session_manager
+    app.state.connection_manager = ConnectionManager()
+    user_store = UserStore(db_path)
+    app.state.user_store = user_store
+    app.state.housekeeping = HousekeepingService(msg_db_path, log_dir, user_store)
+    app.state.template_store = TemplateStore(data_dir)
+    app.state.scenario_store = ScenarioStore(data_dir)
+    conn_manager: ConnectionManager = app.state.connection_manager
+    app.state.scenario_runner = ScenarioRunner(
+        session_manager, app.state.template_store, conn_manager.broadcast_scenario_event
+    )
+
+    # API routers
+    app.include_router(auth.router, prefix="/api/auth")
+    app.include_router(setup.router, prefix="/api/setup")
+    app.include_router(admin.router, prefix="/api/admin")
+    app.include_router(sessions.router, prefix="/api/sessions")
+    app.include_router(messages.router, prefix="/api/sessions")
+    app.include_router(fix_spec.router, prefix="/api/fix-spec")
+    app.include_router(templates.router, prefix="/api/templates")
+    app.include_router(scenarios.router, prefix="/api/scenarios")
+    app.include_router(branding.router, prefix="/api")
+    app.include_router(ws.router)
+
+    # Serve built React app from fixture/static/
+    static_dir = os.path.join(os.path.dirname(__file__), "..", "static")
+    static_dir = os.path.abspath(static_dir)
+
+    if os.path.isdir(static_dir) and os.listdir(static_dir):
+        # Serve hashed JS/CSS bundles
+        app.mount("/assets", StaticFiles(directory=os.path.join(static_dir, "assets")), name="assets")
+
+        # Serve favicon explicitly
+        @app.get("/favicon.svg")
+        async def favicon():
+            return FileResponse(os.path.join(static_dir, "favicon.svg"))
+
+        # Catch-all: return index.html for all SPA routes (/login, /dashboard, etc.)
+        @app.get("/{path_name:path}")
+        async def serve_spa(path_name: str):
+            return FileResponse(os.path.join(static_dir, "index.html"))
+    else:
+        # Frontend not built yet — serve a placeholder
+        @app.get("/")
+        def root():
+            return {
+                "message": "FIXture API is running. Build the frontend with: cd frontend && npm run build"
+            }
+
+    return app

fixtureqa-0.1.0/fixture/api/connection_manager.py

@@ -0,0 +1,161 @@
+"""
+Bridges the SessionManager event system to async WebSocket clients.
+
+fixcore callbacks fire on the asyncio event loop — no thread-crossing needed.
+"""
+
+import asyncio
+from datetime import datetime, timezone
+
+from fastapi import WebSocket
+from starlette.websockets import WebSocketState
+
+from ..core.events import SessionEvent, EventType
+from ..core.message_log import LogEntry
+
+
+def _now_iso() -> str:
+    return datetime.now(tz=timezone.utc).isoformat()
+
+
+def _serialize_event(event: SessionEvent) -> dict:
+    p = event.payload
+    if event.event_type == EventType.SESSION_STATUS_CHANGED:
+        return {
+            "type": "session_status",
+            "session_id": event.session_id,
+            "status": p.get("status"),
+            "status_changed_at": p.get("status_changed_at"),
+            "last_heartbeat_at": p.get("last_heartbeat_at"),
+            "ts": _now_iso(),
+        }
+    elif event.event_type in (EventType.MESSAGE_RECEIVED, EventType.MESSAGE_SENT):
+        return {
+            "type": "message",
+            "session_id": event.session_id,
+            "direction": "IN" if event.event_type == EventType.MESSAGE_RECEIVED else "OUT",
+            "admin": p.get("admin", False),
+            "seq_num": p.get("seq_num", 0),
+            "msg_type": p.get("msg_type", ""),
+            "msg_type_name": p.get("msg_type_name", ""),
+            "ts": _now_iso(),
+            "fields": {str(k): v for k, v in p.get("fields", {}).items()},
+            "raw": p.get("raw", ""),
+        }
+    elif event.event_type == EventType.ENGINE_ERROR:
+        return {
+            "type": "engine_error",
+            "session_id": event.session_id,
+            "error": p.get("error", ""),
+            "ts": _now_iso(),
+        }
+    return {"type": "unknown", "session_id": event.session_id, "ts": _now_iso()}
+
+
+class _ConnInfo:
+    __slots__ = ("uid", "is_admin")
+
+    def __init__(self, uid: str, is_admin: bool):
+        self.uid = uid
+        self.is_admin = is_admin
+
+
+class ConnectionManager:
+    """
+    Tracks all active WebSocket connections and fans out events to them.
+
+    Connections can subscribe to a specific session_id or to all sessions ("*").
+    Each connection carries a uid and is_admin flag for broadcast filtering.
+    """
+
+    def __init__(self):
+        # session_id (or "*") -> dict[WebSocket, _ConnInfo]
+        self._clients: dict[str, dict[WebSocket, _ConnInfo]] = {}
+
+    # ------------------------------------------------------------------
+    # Called from async context (WS handler)
+    # ------------------------------------------------------------------
+
+    async def connect(self, websocket: WebSocket, session_id: str = "*",
+                      uid: str = "", is_admin: bool = False) -> None:
+        await websocket.accept()
+        with self._lock:
+            self._clients.setdefault(session_id, {})[websocket] = _ConnInfo(uid, is_admin)
+
+    def disconnect(self, websocket: WebSocket, session_id: str = "*") -> None:
+        with self._lock:
+            clients = self._clients.get(session_id, {})
+            clients.pop(websocket, None)
+
+    # ------------------------------------------------------------------
+    # Called from the asyncio event loop (fixcore callbacks / scenario runner)
+    # ------------------------------------------------------------------
+
+    def sync_event_handler(self, event: SessionEvent) -> None:
+        """Registered with SessionManager.subscribe(). Called on the event loop."""
+        payload = _serialize_event(event)
+        asyncio.create_task(self._broadcast(event.session_id, payload, event.owner_uid))
+
+    def broadcast_scenario_event(self, uid: str, data: dict) -> None:
+        """Schedule delivery to all WS connections for uid."""
+        asyncio.create_task(self._broadcast_to_user(uid, data))
+
+    # ------------------------------------------------------------------
+    # Internal async broadcast
+    # ------------------------------------------------------------------
+
+    async def _broadcast(self, session_id: str, payload: dict, owner_uid: str) -> None:
+        with self._lock:
+            # Specific-session subscribers
+            specific = dict(self._clients.get(session_id, {}))
+            # Wildcard subscribers
+            wildcard = dict(self._clients.get("*", {}))
+
+        # Build target set: connections that may receive this event
+        # A connection receives the event if:
+        #   - it is an admin, OR
+        #   - its uid matches the session owner
+        targets: dict[WebSocket, _ConnInfo] = {}
+        for ws, info in {**specific, **wildcard}.items():
+            if info.is_admin or info.uid == owner_uid:
+                targets[ws] = info
+
+        dead: list[tuple[WebSocket, str]] = []
+        for ws in targets:
+            try:
+                if ws.client_state == WebSocketState.CONNECTED:
+                    await ws.send_json(payload)
+            except Exception:
+                with self._lock:
+                    for key, sockets in self._clients.items():
+                        if ws in sockets:
+                            dead.append((ws, key))
+
+        with self._lock:
+            for ws, key in dead:
+                self._clients.get(key, {}).pop(ws, None)
+
+    async def _broadcast_to_user(self, uid: str, data: dict) -> None:
+        """Send data to all WS connections belonging to uid."""
+        with self._lock:
+            all_clients = {}
+            for sockets in self._clients.values():
+                for ws, info in sockets.items():
+                    all_clients[ws] = info
+
+        dead: list[tuple[WebSocket, str]] = []
+        for ws, info in all_clients.items():
+            if info.uid != uid and not info.is_admin:
+                continue
+            try:
+                if ws.client_state == WebSocketState.CONNECTED:
+                    await ws.send_json(data)
+            except Exception:
+                with self._lock:
+                    for key, sockets in self._clients.items():
+                        if ws in sockets:
+                            dead.append((ws, key))
+
+        with self._lock:
+            for ws, key in dead:
+                self._clients.get(key, {}).pop(ws, None)

fixtureqa-0.1.0/fixture/api/deps.py

@@ -0,0 +1,73 @@
+from fastapi import Depends, HTTPException, status
+from fastapi.security import OAuth2PasswordBearer
+from jose import JWTError
+from starlette.requests import HTTPConnection
+
+from ..core.session_manager import SessionManager
+from ..core.user_store import User, UserStore
+from ..core.auth import decode_token
+from ..core.housekeeping import HousekeepingService
+from ..core.template_store import TemplateStore
+from ..core.scenario_store import ScenarioStore
+from ..core.scenario_runner import ScenarioRunner
+from .connection_manager import ConnectionManager
+
+oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/api/auth/login")
+
+
+def get_session_manager(request: HTTPConnection) -> SessionManager:
+    return request.app.state.session_manager
+
+
+def get_conn_manager(request: HTTPConnection) -> ConnectionManager:
+    return request.app.state.connection_manager
+
+
+def get_user_store(request: HTTPConnection) -> UserStore:
+    return request.app.state.user_store
+
+
+def get_current_user(
+    request: HTTPConnection,
+    token: str = Depends(oauth2_scheme),
+) -> User:
+    credentials_exception = HTTPException(
+        status_code=status.HTTP_401_UNAUTHORIZED,
+        detail="Invalid or expired token",
+        headers={"WWW-Authenticate": "Bearer"},
+    )
+    try:
+        payload = decode_token(token)
+        uid: str = payload.get("sub", "")
+        if not uid:
+            raise credentials_exception
+    except JWTError:
+        raise credentials_exception
+
+    store: UserStore = request.app.state.user_store
+    user = store.get_by_uid(uid)
+    if user is None or not user.is_active:
+        raise credentials_exception
+    return user
+
+
+def require_platform_admin(user: User = Depends(get_current_user)) -> User:
+    if user.role != "platform_admin":
+        raise HTTPException(status_code=status.HTTP_403_FORBIDDEN, detail="Admin access required")
+    return user
+
+
+def get_housekeeping(request: HTTPConnection) -> HousekeepingService:
+    return request.app.state.housekeeping
+
+
+def get_template_store(request: HTTPConnection) -> TemplateStore:
+    return request.app.state.template_store
+
+
+def get_scenario_store(request: HTTPConnection) -> ScenarioStore:
+    return request.app.state.scenario_store
+
+
+def get_scenario_runner(request: HTTPConnection) -> ScenarioRunner:
+    return request.app.state.scenario_runner