PJS - Priority JSON Streaming Protocol

Priority-based streaming | Progressive loading | Zero-copy operations | WebAssembly ready

High-performance Rust library for priority-based JSON streaming with SIMD acceleration. Stream large JSON responses progressively, delivering critical data first while background data loads asynchronously.

Important

GAT migration (1.82x faster), HTTP adapter with CQRS, comprehensive security hardening with bounded iteration and input validation. Requires nightly Rust for zero-cost async abstractions.

Features

• Blazing Fast - SIMD-accelerated parsing, GAT-based zero-cost abstractions (1.82x faster than async_trait)
• Smart Streaming - Priority-based delivery sends critical data first, skeleton-first rendering
• Memory Efficient - Optimized progressive loading, bounded memory usage, zero-copy operations
• WebAssembly - Browser and Node.js support with compact bundle (~70KB gzipped)
• Secure - Defense-in-depth decompression protection, DoS prevention, input validation
• Schema Aware - Automatic compression and semantic analysis
• Production Ready - Clean Architecture, comprehensive test suite, Prometheus metrics

Performance

Benchmark	Result	Notes
GAT Async	1.82x faster	Static dispatch vs async_trait virtual calls

Reproducible benchmarks: cargo bench -p pjs-bench

Installation

cargo add pjson-rs

Or add to Cargo.toml:

[dependencies]
pjson-rs = "0.6"

Note

Requires Rust 1.89+ (nightly). See MSRV policy for details.

Quick Start

Rust HTTP Server

use pjson_rs::infrastructure::http::axum_adapter::create_pjs_router;#[tokio::main]asyncfnmain(){let app = create_pjs_router().with_state(app_state);let listener = tokio::net::TcpListener::bind("127.0.0.1:3000").await?;
axum::serve(listener, app).await?;}

Start server and test:

# Run priority streaming demo
cargo run --example simple_priority_demo
# Or run with compression support
cargo run --example compression_demo --features compression

WebAssembly (Browser)

npm install @pjson/wasm

PriorityStream API (Recommended)

<scripttype="module">importinit,{PriorityStream,PriorityConstants}from'./pkg/pjs_wasm.js';asyncfunctionmain(){awaitinit();conststream=newPriorityStream();stream.setMinPriority(PriorityConstants.MEDIUM());// Register callbacksstream.onFrame((frame)=>{console.log(`${frame.type} [${frame.priority}]: ${frame.payload}`);if(frame.priority>=80){updateUI(JSON.parse(frame.payload));// High priority first}});stream.onComplete((stats)=>{console.log(`Completed: ${stats.totalFrames} frames in ${stats.durationMs}ms`);});// Start streamingstream.start(JSON.stringify({id: 123,name: "Alice",bio: "..."}));}main();</script>

Tip

Use the PriorityStream API for automatic frame handling and built-in security limits. Ideal for real-time dashboards and progressive loading.

Simple Parser API

<scripttype="module">importinit,{PjsParser,PriorityConstants}from'./pkg/pjs_wasm.js';asyncfunctionmain(){awaitinit();constparser=newPjsParser();constframes=parser.generateFrames(JSON.stringify({user_id: 123,name: "Alice"}),PriorityConstants.MEDIUM());frames.forEach(frame=>{if(frame.priority>=90){updateUI(frame.data);// Critical data first}});}main();</script>

Interactive Demo

Try the Browser Demo with transport switching, performance benchmarks, and real-time metrics.

WebAssembly (Node.js)

importinit,{PjsParser}from'@pjson/node';import{readFile}from'fs/promises';constwasmBuffer=awaitreadFile('./node_modules/@pjson/node/pjs_wasm_bg.wasm');awaitinit(wasmBuffer);constparser=newPjsParser();constframes=parser.generateFrames(JSON.stringify(data),50);frames.forEach(frame=>{console.log(`Priority ${frame.priority}: ${frame.frame_type}`);});

Build WASM from Source

# Install wasm-pack
curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
# Build for different targets
wasm-pack build crates/pjs-wasm --target web --release # Browsers
wasm-pack build crates/pjs-wasm --target nodejs --release # Node.js
wasm-pack build crates/pjs-wasm --target bundler --release # Webpack/Rollup

Use Cases

• Real-time Dashboards - Show key metrics instantly, load details progressively
• Mobile Apps - Optimize for slow networks, critical data first
• E-commerce - Product essentials load immediately, reviews/images follow
• Financial Platforms - Trading data prioritized over historical charts
• Gaming Leaderboards - Player rank appears instantly, full list streams in

Building

Prerequisites

Warning

This project requires nightly Rust for Generic Associated Types (GAT) features. Stable Rust is not supported.

rustup install nightly
rustup override set nightly

Build Commands

# Standard build
cargo build --release
# Run tests with nextest
cargo nextest run --workspace
# Run benchmarks
cargo bench -p pjs-bench
# Run demo servers
cargo run --manifest-path crates/pjs-demo/Cargo.toml --bin interactive-demo-server --features "simd-auto,schema-validation,compression,http-server,websocket-server"
cargo run --manifest-path crates/pjs-demo/Cargo.toml --bin simple-demo-server --features "simd-auto,http-server"

Feature Flags

Tip

Start with default features. Add extras only when needed to keep compile times fast.

Feature	Description	Default
simd-auto	Auto-detect SIMD support at runtime	✅ Yes
simd-avx2	Force AVX2 SIMD path	No
simd-avx512	Force AVX-512 SIMD path (sonic-rs)	No
simd-sse42	Force SSE4.2 SIMD path	No
simd-neon	Force ARM NEON SIMD path	No
schema-validation	Schema validation engine	✅ Yes
compression	zlib/gzip/brotli/zstd decompression with per-session dictionaries	✅ Yes
partial-parse	Streaming partial JSON parsing (jiter backend)	No
http-server	Axum HTTP server and CQRS endpoints	✅ Yes
http-client	reqwest-based HTTP client	✅ Yes
http-auth-jwt	JWT authentication middleware	No
websocket-server	WebSocket transport (server)	✅ Yes
websocket-client	WebSocket transport (client)	✅ Yes
mimalloc	Use mimalloc as global allocator	No
metrics	Prometheus metrics endpoint	No

Note: The jemalloc feature was removed in v0.6.0 (breaking change). Switch to mimalloc or the system allocator.

Security

PJS includes built-in security features to prevent DoS attacks:

import{PriorityStream,SecurityConfig}from'@pjson/wasm';constsecurity=newSecurityConfig().setMaxJsonSize(5*1024*1024)// 5 MB limit.setMaxDepth(32);// 32 levels maxconststream=PriorityStream.withSecurityConfig(security);

Default Limits:

• Max JSON size: 10 MB
• Max nesting depth: 64 levels
• Max array elements: 10,000
• Max object keys: 10,000

Important

Security: Comprehensive multi-layer protection including bounded iteration (DoS prevention), input validation, and 4-layer defense-in-depth decompression protection against compression bombs (CVSS 7.5 vulnerabilities fixed).

Decompression Security:

• MAX_RLE_COUNT: 100,000 items per run
• MAX_DELTA_ARRAY_SIZE: 1,000,000 elements
• MAX_DECOMPRESSED_SIZE: 10 MB total
• Integer overflow protection: Checked arithmetic throughout

Architecture

PJS follows Clean Architecture with Domain-Driven Design:

• pjs-domain - Pure business logic, WASM-compatible
• pjs-wasm - WebAssembly bindings with PriorityStream API, security limits
• pjs-core - Rust implementation with HTTP/WebSocket integration
• pjs-demo - Interactive demo servers with real-time streaming
• pjs-js-client - TypeScript/JavaScript client with WasmBackend transport
• pjs-bench - Comprehensive performance benchmarks

Key Features:

• GAT Migration: Zero-cost async abstractions (1.82x faster than async_trait)
• HTTP Adapter: 8 REST endpoints with CQRS pattern
• Security Hardening: Bounded iteration, input validation, decompression bomb protection
• Generic Type System: Type-safe Id wrappers, generic InMemoryStore<K, V>
• Platform Support: Windows, Linux, macOS validated

Contributing

Contributions welcome! Please ensure:

rustup override set nightly
cargo clippy --workspace -- -D warnings
cargo nextest run --workspace --all-features
cargo +nightly fmt --check

See CONTRIBUTING.md for guidelines.

License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT License (LICENSE-MIT)

at your option.

Resources

• Protocol Specification
• Changelog
• Benchmarks
• Discussions

---

PJS: Priority-based JSON streaming for instant user experiences.