Changelog

All notable changes to the Asok Framework are documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[0.8.0] - 2026-10-11

Performance & Scaling: Real-Time WebSocket Clustering, High-Concurrency SQLite WAL, and Prometheus Observability

This release introduces distributed WebSocket scaling with Redis Pub/Sub broadcast adapters, multi-process SQLite WAL concurrency optimizations with automatic retry backoff, built-in zero-dependency Prometheus metrics (/metrics), health check probes (/healthz), cross-engine slow query alerting, and HTTP 103 Early Hints acceleration.

---

Added

• Native SaaS Multi-Tenancy (asok.orm.tenant, asok.middleware.TenantMiddleware):

  • Scoped database and schema isolation with tenant_context(tenant_id).

  • Automatic ORM query routing for all reads and writes via TenantRouter.

  • TenantMiddleware with automatic resolution from X-Tenant-ID header, subdomains (acme.example.com), query parameters (?tenant=acme), or custom extractors.

  • Registries register_tenant_database(), set_tenant_resolver(), and environment template ASOK_TENANT_DB_TEMPLATE.

• Distributed Tracing (W3C TraceContext & OpenTelemetry, asok.core.tracing, asok.middleware.TracingMiddleware):

  • Full W3C traceparent (00-{trace_id}-{span_id}-{flags}) parsing and formatting.

  • Automatic propagation of traceparent, X-Trace-ID, and X-Span-ID in HTTP responses.

  • Programmatic span creation via with tracer.start_span("name") as span:.

  • OpenTelemetry-compliant dictionary export (span.to_dict()) and exception recording.

• Resilient Background Tasks & Admin DLQ Dashboard (asok.background, asok.admin.views.jobs):

  • Exponential backoff retry delays with randomized jitter (compute_retry_delay).

  • Integrated Dead Letter Queue (DLQ) support for Redis and local task backends.

  • DLQ management APIs: get_dlq_jobs(), get_dlq_count(), get_queue_counts(), retry_dlq_job(), retry_all_dlq_jobs(), delete_dlq_job(), purge_dlq().

  • Interactive Admin Web Dashboard at /admin/jobs with queue depth metrics, failed job inspection, retry, bulk retry, and purge controls.

• Distributed WebSocket Cluster Adapters (asok.ws.adapter):

  • BaseWebSocketAdapter unified cluster broadcast interface.

  • InMemoryWebSocketAdapter default adapter for standalone server processes.

  • RedisWebSocketAdapter enabling multi-server horizontal cluster scaling via Redis Pub/Sub channels (asok:ws:*).

  • Configuration options WS_ADAPTER ("memory" or "redis") and WS_REDIS_URL.

• Database Concurrency & SQLite WAL Optimizations (asok.orm.engines.sqlite):

  • Automated WAL mode configuration (PRAGMA journal_mode = WAL;).

  • Lock mitigation pragmas (PRAGMA busy_timeout = 5000;, PRAGMA synchronous = NORMAL;).

  • Automatic exponential retry backoff on database is locked errors during query execution and autocommit transactions.

• Built-in Prometheus Observability & Healthchecks (asok.core.metrics):

  • Zero-dependency thread-safe Prometheus text exposition endpoint (/metrics).

  • Endpoints /health, /healthz, and /__health verifying database connectivity, cache health, and process uptime.

  • Request counters (asok_http_requests_total), latency tracking (asok_http_request_duration_seconds), and cardinality protection against memory exhaustion.

  • Active WebSocket connections gauge (asok_websocket_active_connections).

• Slow Query Alerting & Cross-Engine Profiling (asok.orm.proxy):

  • Configurable SLOW_QUERY_THRESHOLD_MS (default: 100ms) with structured warning logs: [SLOW QUERY] ...ms.

  • Unified database query metrics across SQLite, PostgreSQL, and MySQL engines.

  • Added batch operation tracing for executemany().

• HTTP 103 Early Hints & Preload Helpers (asok.core.smart_streamer):

  • Added send_early_hints() and build_preload_link() with injection-safe sanitization for asset acceleration.

• Developer Toolbar SPA Router Inspector: Live tracking of current SPA route, dynamic path parameters (:param), route metadata (asok-meta:title), and mounted template components.

• ORM & Security Hardening (v0.8.0):

  • Model.update_safe(**values) and _strict=False: tolerant updates ignoring undeclared fields (_csrf, submit actions, extra form kwargs).

  • Query.latest(column, fallback_to_id=True) and oldest(column, fallback_to_id=True): graceful fallback to id for dynamic ordering.

  • Fail-closed WebSocket GraphQL subscriptions (GRAPHQL_AUTHORIZE) when conn.request is None.

  • Default GRAPHQL_ALLOW_UNAUTHENTICATED_QUERIES=True for read queries.

  • Fail-secure hard stop in production for MagicLink with in-memory cache, with configurable opt-in MAGIC_LINK_ALLOW_IN_MEMORY=True.

  • 12-factor .env loading with collision warning via warnings.warn + logger.warning, and optional override via ASOK_ENV_OVERRIDE=true.

  • Sensitive error masking in Live Components for PermissionError, AttributeError, KeyError, and ValueError in production.

  • ALLOW_WEBSOCKET_NO_ORIGIN=True / WS_ALLOW_NO_ORIGIN=true escape hatch for backend workers, CLI, and health checks.

  • ASOK_ALLOWED_TENANTS env var support for global tenant allowlisting in TenantMiddleware.

[0.7.0] - 2026-09-20

Major Release: Native Declarative SPA Router, Zero-Code Form Submissions, Directional Page Transitions & Security Hardening

This release introduces Asok’s native client-side SPA routing system with zero page reloads, declarative JSON form submissions (asok-fetch-post), full optional chaining and nullish coalescing support in template expressions, directional page transitions, and comprehensive security hardening across the framework.

---

Added

• Native Client-Side SPA Declarative Router (asok/core/assets/asok_router.js, asok_router.min.js):

  • Declarative client-side routing container <main asok-router> with <template asok-route="/path">.

  • Dynamic parameterized route matching (:param) with automatic URL decoding into window.AsokRouter.route.params.

  • Route metadata injection (asok-meta:title, asok-meta:description, asok-meta:og:*) per route view.

  • Seamless client-side navigation links:

    • Standard HTML syntax: <a href="/path" asok-link> (SEO and accessibility friendly).

    • Compact syntax: <a asok-link="/path"> (automatically populates href).

  • Active link styling with asok-active-class:

    • Full support for multiple space-separated classes (e.g. Tailwind utility classes: asok-active-class="font-bold underline text-blue-600").

    • Safely tokenizes and applies individual classes to classList.add(...) and classList.remove(...) without throwing DOMTokenList errors.

  • Automatic external link handling, honoring target="_blank", download, and rel="external".

  • Programmatic Navigation API: window.AsokRouter.navigate(path, replace = false), window.AsokRouter.update(), and window.AsokRouter.matchPattern(pattern, path).

  • Synchronous Route Store: window.AsokRouter.route (.path, .params, .query, .hash) and shortcut getters.

  • Route Change Observers:

    • JavaScript listener: window.AsokRouter.onRouteChange(callback) (and alias afterEach(callback)), triggered immediately and on every navigation.

    • Standard custom DOM event: window.addEventListener('asok:routechange', (e) => ...).

  • Automatic smooth scroll to top on SPA route changes.

• Zero-Code Declarative Form Submissions (asok-fetch-post, asok-fetch-post-async):

  • Zero-JS declarative JSON POST form submission directive: <form asok-fetch-post="/api/endpoint" asok-reset>.

  • Automatic extraction and merging of native form inputs (FormData) and reactive state variables into a JSON payload.

  • Automatic CSRF protection header injection (X-CSRF-Token).

  • Automatic reactive state updates: loading, response (customizable via asok-fetch-as), error, status, statusCode, and ok.

  • Automatic form and model reset upon success via asok-reset.

  • Flexible trigger customization via asok-fetch-on (submit, click, load).

• Template Expression Enhancements (asok/core/_expr_validator.py):

  • Added support for JavaScript Optional Chaining (?., ?.[, ?.()) and Nullish Coalescing (??) in directive expressions with server-side AST security validation.

  • Enables safe property access on initially null state (e.g. asok-text="result?.message").

• Directional Slide Page Transitions (asok/core/assets/asok_transitions.css):

  • Added directional slide transitions: slide-left, slide-right, slide-up, and slide-down.

  • Pre-applied transition classes and layout shift prevention wrappers for seamless visual continuity.

Security & Robustness Hardening

• SPA Fallback Path Protection (asok/core/routing.py):

  • Hardened SPA fallback matching to prevent serving fallback HTML on sensitive dotfiles (.env, .git, etc.) or path traversal requests.

• Safe URL & Query String Hardening (asok/utils/security.py):

  • Hardened safe_next_url and raw query string validation against open redirects and header injection attacks.

• WSGI & Request Robustness (asok/core/wsgi.py, asok/request/request.py, asok/request/response.py):

  • Enhanced error handling, unhandled exception fallbacks, and JSON payload accessor resilience.

• Framework Version Bump:

  • Bumped version to 0.7.0 across framework metadata, CLI tools, OpenAPI spec defaults, and developer debug toolbar.

[0.6.0] - 2026-07-29

⚡ Major Release: Zero-JS UI Directives, Automated Database Backup CLI, Admin Graphical RBAC & Trash Bin, Security Audit & Tooling Pipeline

This major release brings extensive enhancements across the entire Asok Framework ecosystem: zero-JS reactive UI directives, an automated database backup system with CLI management, a revamped Admin interface with graphical RBAC permissions, trash bin & soft-delete manager, active session management, strict security hardening, Radon Grade A complexity refactoring, and a complete code audit & analysis pipeline in the Makefile.

---

Added

• Automated Database Backup Engine & CLI (asok/backup.py, asok/cli/backup.py):

  • Implemented automated database snapshotting supporting SQLite, PostgreSQL, and MySQL.

  • Added CLI commands: asok backup create, asok backup list, asok backup restore, and asok backup prune.

  • Configurable backup management: DATABASE_BACKUP_ENABLED, DATABASE_BACKUP_URL, DATABASE_BACKUP_PATH, DATABASE_BACKUP_MAX_SNAPSHOTS, and DATABASE_BACKUP_INTERVAL.

• Zero-JS Reactive UI & Utility Directives Engine (asok/core/assets/asok_directives.js):

  • Keyed List Reconciliation: Added asok-key (asok-key-ref) for per-item keyed DOM list reconciliation in asok-for loops.

  • Theme Toggle: Added asok-theme-toggle (data-asok-theme-toggle, data-theme-toggle) with anti-FOUC script and OS preference sync.

  • Cookie Consent: Added GDPR compliance attributes: asok-cookie-banner, asok-cookie-accept, asok-cookie-reject, asok-cookie-reset, and script-blocking asok-cookie-script (data-cookie-*).

  • Dismissible UI: Added asok-dismiss and asok-dismiss-trigger (data-asok-dismiss, data-dismiss, data-asok-dismiss-trigger, data-dismiss-trigger) with localStorage state persistence.

  • Clipboard Copy: Added asok-copy (data-asok-copy, data-copy) for code blocks, inputs, and text elements with visual feedback.

  • Accessible Modals: Added asok-modal, asok-modal-open, asok-modal-close (data-asok-modal*, data-modal*) with Escape key and backdrop handling.

  • Smooth Scroll: Added asok-scroll-top and asok-scroll-to (data-asok-scroll-*, data-scroll-*) with position threshold detection.

  • Character Counter: Added asok-char-count (data-asok-char-count, data-char-count) for inputs and textareas.

  • Tabbed Interfaces: Added asok-tabs, asok-tab, and asok-tab-panel (data-asok-tab*, data-tab*) with ARIA accessibility.

  • Page Progress Bar: Added asok-progress (data-asok-progress, data-progress) for automatic top navigation progress bar updates.

  • HTML5 Validation Compliance: Supported data-asok-* and data-* attribute aliases across all directives.

• Admin Graphical RBAC & Permissions Matrix (asok/admin/access_rules.py, asok/admin/views/crud.py):

  • Graphical RBAC editor in the Admin panel for visually assigning model and action permissions per role.

  • Column-level & Row-level Scope authorization rules for fine-grained user data isolation.

  • Read-only system models protection and model-level field authorization.

• Admin Trash Bin & Soft Delete Management (asok/admin/templates/trash.html):

  • Built-in Trash Bin manager allowing administrators to view, restore, or permanently purge soft-deleted records.

• Active Session Management (asok/admin/templates/active_sessions.html):

  • Admin view to list, inspect, and revoke active user sessions in real time.

• Admin Asset Integrations:

  • Integrated local Flatpickr date/time pickers and Chart.js for dashboard analytics.

Improved

• Radon Cyclomatic Complexity Refactoring:

  • Refactored _clean_url_html() and _is_dangerous_protocol_html() in asok/utils/html_sanitizer.py to achieve Grade A (complexity 2).

  • 100% of functions and methods across the framework now satisfy Grade A cyclomatic complexity.

• Declarative Migrations & ORM Improvements:

  • Enhanced migration auto-detector and schema backfilling for NOT NULL columns.

  • Added foreign key auto-accessor methods and automated pivot table provisioning (role_user).

• Template Filters:

  • Added timestamp filter epoch ({{ timestamp | epoch('%d/%m/%Y %H:%M') }}) in asok/templates/filters.py.

Security

• Bandit Security Audit & Non-Cryptographic Hashes:

  • Remediated all Bandit security findings by adding usedforsecurity=False across non-cryptographic hashlib.md5() and hashlib.sha1() calls (asok/admin/core.py, asok/core/_asset_injector.py, asok/core/static.py, asok/orm/query.py, asok/templates/compiler.py, asok/templates/engine.py, asok/ws/protocol.py). High-severity Bandit security issues reduced from 8 to 0.

• Hardcoded Secrets & Token Verification:

  • Integrated dodgy secret scanner; verified 0 hardcoded passwords, tokens, or API keys in the codebase ({"warnings": []}).

• Session & Sandbox Hardening:

  • Session key truncation & payload size limits in asok/session.py.

  • Strict CSRF Origin/Referer verification and template sandbox undefined value handling (asok/templates/undefined.py).

Fixed

• ORM Async Querybuilder Indentation:

  • Resolved a critical indentation bug in asok/orm/query.py where terminal async methods (get_async(), first_async(), paginate_async(), count_async(), etc.) were indented inside _compute_page_counts after its return statement.

• Dead Code Cleanup (Vulture Audit):

  • Removed unused internal helper functions _collect_config_morph_models (asok/admin/forms.py), _slugify_name and _humanize (asok/admin/utils.py), and _build_migration_sql (asok/cli/generators.py). Renamed parameter expected_type to _expected_type in template.py.

Documentation & Tooling

• Makefile Analysis Pipeline:

  • Added bandit, audit (pip-audit), secrets (dodgy), vulture, and pyright targets to Makefile for one-command code quality and security scanning.

• Documentation Updates:

  • Documented database backup configuration parameters in Section 9 (Database & ORM) across all documentation suites.

  • Documented epoch filter in Section 4 (Templates).

  • Integrated full CHANGELOG.md into python_docs/ suite and added changelog to Sphinx index.md toctree.

  • Cleaned up redundant manual footer navigation links from python_docs/.

[0.5.1] - 2026-06-24

Fixed

• CLI createsuperuser Pivot Table Provisioning: Resolved a database table error/warning in the createsuperuser command where attempting to attach the admin role failed if the role_user pivot table did not exist.

• Documentation Roadmap Width: Converted the Markdown comparison table in README.md to HTML with a 100% width layout to ensure correct full-width rendering in all markdown engines.