b4n1-boost

The Python Accelerator. Native middleware for Django, FastAPI and Flask — JSON 10x faster, compression 28x faster.

b4n1-boost ships as a precompiled native extension, so there is nothing to compile on your machine. Drop it into an existing project and the hot paths — serialization, compression, static assets — run in native code while your application code stays exactly the same.

What it does

Who it is for

• Teams whose Django or FastAPI app is CPU-bound on serialization or compression
• Applications serving large JSON payloads or heavy static assets
• Projects that want native speed without adding a service (no Redis, no broker)

Where to go next

• Quick Start — one import, running in under a minute
• Installation — supported platforms and Python versions
• Performance — the measured numbers and how to reproduce them
• Python SDK — the full API surface

Design notes

Everything runs in-process. There is no daemon, no sidecar and no network hop: b4n1-boost is a library you import. When the native core is unavailable, the documented fallbacks are explicit — the package never silently pretends a fast path is active. Call status() at any time to see exactly which engines are live (see Status & Diagnostics).

Quick Start

Install, import, and the accelerator is live.

pip install b4n1-boost

Django

import b4n1_boost

report = b4n1_boost.install_django()
# Appends DjangoBoostMiddleware to settings.MIDDLEWARE
# {'framework': 'Django', 'middleware_installed': True, ...}

FastAPI

from fastapi import FastAPI
import b4n1_boost

app = FastAPI()
b4n1_boost.install_fastapi(app)

Flask

from flask import Flask
import b4n1_boost

app = Flask(__name__)
b4n1_boost.install_flask(app)

Auto-detection

If you would rather not name the framework, autoboost() detects it:

import b4n1_boost
b4n1_boost.autoboost()   # Detects Django/FastAPI/Flask automatically

Install everything at once

import b4n1_boost

report = b4n1_boost.boost_all()
# Applies: compression + ETag + security headers + CORS
#          + rate limiting + health check
# {'framework': 'Django',
#  'applied': ['compression', 'etag', ...],
#  'middleware_count': 6}

Use the fast paths directly

The installers wire up middleware. The utilities are usable on their own:

from b4n1_boost import NativeJson, canonicalize_json, validate_json, compress

payload = {"users": [{"id": i, "name": "user"} for i in range(500)]}

body = NativeJson.dumps(payload)          # 10x faster than json.dumps
assert validate_json(body)                # True
assert canonicalize_json({"z": 1, "a": 2}) == '{"a":2,"z":1}'

wire = compress(body, "zstd")             # 28x faster than gzip

Verify it loaded

import b4n1_boost

print(b4n1_boost.status())
# {'native_extension': True, 'version': '0.3.12', 'features': {...}}

If native_extension is False, the native core did not load — see Status & Diagnostics for how to diagnose it before you chase performance numbers that will not materialise.

Next

• Installation for platform and Python version details
• Performance for the benchmark table and how to run it
• Python SDK for the complete API

Installation

pip install b4n1-boost

Precompiled wheels are published for every supported platform. There is no compiler step, no build backend invocation and no system dependency to install first.

Supported platforms

Supported Python versions

The requirement is >=3.10. Wheels are built against the stable ABI, so a single wheel per platform covers every supported interpreter.

Verify the install

import b4n1_boost

status = b4n1_boost.status()
assert status["native_extension"] is True, (
    "native core did not load: %s" % status
)
print("b4n1-boost", status["version"], "ready")

If native_extension is False, pip fell back to a pure-Python path. See Status & Diagnostics — do not benchmark until this reads True.

Pinning a version

pip install b4n1-boost==0.3.12

Upgrading

pip install --upgrade b4n1-boost

After an upgrade, re-run the verification snippet. A stale cached extension from a previous version is a common source of confusing benchmark results.

Uninstalling

pip uninstall b4n1-boost

No files are written outside the virtual environment, and no background process is left running.

Installing the other SDKs

b4n1-boost shares one native core across several language SDKs:

Performance

All figures below are measured against the Python standard library on the same machine, same input, same process. They are a starting point: your numbers depend on payload shape, hardware and interpreter version.

Headline numbers

Running the benchmarks yourself

import b4n1_boost

report = b4n1_boost.run_benchmarks(iterations=100_000)
print(report)

Run it on the hardware you actually deploy on. A laptop benchmark does not predict production throughput, and the ratio between native and stdlib paths moves with payload size.

What makes JSON fast

from b4n1_boost import NativeJson

# Standard path — uses the fastest available backend
body = NativeJson.dumps(users)

# Direct path — skips the intermediate conversion entirely
body = NativeJson.dumps_direct(users)

# Batch: N serializations inside a single interpreter-lock acquire
bodies = NativeJson.batch_dumps([obj1, obj2, obj3])

batch_dumps is where the largest wins appear for list-shaped workloads, because the per-call overhead that dominates small serializations is paid once rather than N times.

What makes compression fast

from b4n1_boost import compress

wire = compress(payload, "zstd")     # 28x faster than stdlib gzip
wire = compress(payload, "gzip")     # 1.47x faster than stdlib
wire = compress(payload, "brotli")   # best ratio

Compression also runs without holding the interpreter lock, so a large payload being compressed on a worker thread does not stall other requests.

Choosing an algorithm

For static assets the decision is usually automatic — see compress_static_dir in the Python SDK.

Static files

from b4n1_boost import compress_static_file, compress_static_dir

compress_static_file("app/static/app.js", algorithm="zstd")
compress_static_dir("app/static/", algorithm="zstd")

Already-compressed formats are skipped automatically: images, video, audio, fonts and archives are left alone, because re-compressing them costs CPU and yields nothing.

Measuring honestly

A few rules that keep benchmark numbers meaningful:

1. Compare like with like. Same payload, same machine, same process.
2. Warm up first. The first call pays import and allocation costs that do not recur.
3. Report percentiles, not just the mean. A 10x mean improvement with a worse p99 is not an improvement for a user-facing endpoint.
4. State the payload. “10x faster” means nothing without the size and shape of the input that produced it.
5. Verify the native core loaded. Benchmarking a fallback path measures the wrong thing — check status()["native_extension"] first.

Next

• Status & Diagnostics to confirm what is actually running
• Python SDK for the API surface behind these numbers

Python SDK

The primary SDK. Everything here is importable directly from b4n1_boost.

import b4n1_boost

Setup helpers

import b4n1_boost

report = b4n1_boost.boost_all()
print(report["applied"], report["middleware_count"])

JSON

from b4n1_boost import NativeJson, canonicalize_json, validate_json

NativeJson.dumps(data)            # fastest available backend
NativeJson.dumps_direct(data)     # skips the intermediate conversion
NativeJson.batch_dumps([a, b, c]) # N serializations, one lock acquire
NativeJson.batch_loads(bodies)
NativeJson.batch_validate(bodies)

canonicalize_json({"z": 1, "a": 2})   # '{"a":2,"z":1}' — sorted, compact
validate_json('{"valid": true}')      # True

canonicalize_json accepts either a str or a dict and returns a stable, sorted-key, compact representation. Two equivalent objects produce byte-identical output, which is what makes it useful for cache keys and signatures.

Batch helpers

from b4n1_boost import batch_dumps, batch_dumps_direct, batch_loads, batch_validate

bodies = batch_dumps(objects)
valid  = batch_validate(bodies)
objs   = batch_loads(bodies)

Compression

from b4n1_boost import compress

compress(payload, "zstd")     # 28x faster than stdlib gzip
compress(payload, "brotli")   # best ratio
compress(payload, "gzip")     # 1.47x faster than stdlib

Static assets

from b4n1_boost import compress_static_file, compress_static_dir

compress_static_file("app/static/app.js", algorithm="zstd")
compress_static_dir("app/static/", algorithm="zstd")

Images, video, audio, fonts and archives are skipped automatically.

HTML → Markdown

from b4n1_boost import html_to_markdown

html_to_markdown("<h1>Title</h1><p>Content with <b>bold</b></p>")
# '# Title\n\nContent with **bold**'

Useful when you want to hand a page to a language model as text rather than as markup.

Minification

from b4n1_boost.advanced import minify_html, minify_css, minify_js

minify_html("<html>  <body>  Hello  </body>  </html>")
minify_css(css_source)
minify_js(js_source)

JWT validation

from b4n1_boost.advanced import validate_jwt

payload = validate_jwt(token, secret=JWT_SECRET, algorithm="HS256")

Validates HMAC-SHA256 tokens natively, so a service does not need a separate JWT library just to verify incoming tokens.

Worker-thread API

from b4n1_boost import worker_compress, worker_decompress
from b4n1_boost import worker_minify, worker_jwt_validate, worker_shutdown

future = worker_compress(data, "zstd")
compressed = future.result()

Heavy operations run on a background thread. The calling thread is not blocked and the interpreter lock is not held for the duration of the work.

Background tasks

from b4n1_boost import background, pending_tasks, native_async

See Background Tasks.

Telemetry

from b4n1_boost import telemetry_init, capture_error, log_info, log_phase, flush

telemetry_init(dsn="https://...")
capture_error(Exception("something"), context={"user": "123"})
log_info("Request processed", phase="http")
flush()

Telemetry is opt-in. Without an explicit telemetry_init(...) call nothing is emitted.

Introspection

import b4n1_boost

b4n1_boost.__version__       # package version
b4n1_boost.status()          # engines and features actually loaded
b4n1_boost.run_benchmarks()  # hardware benchmarks on this machine

Full export list

import b4n1_boost
print(b4n1_boost.__all__)

__all__ is the authoritative list of public names. Anything not in it is internal and may change between minor versions.

See also

• Middleware Reference — every middleware class in detail
• Django & DRF Accelerators — ORM and serializer speedups
• Status & Diagnostics — verifying what loaded

Middleware Reference

Middleware is where most of the practical speedup lives. Each class is independent — use one, or stack them.

Compression

from b4n1_boost.middleware import B4N1BoostCompressionMiddleware

app.wsgi_app = B4N1BoostCompressionMiddleware(app.wsgi_app, min_size=1024)

Content-Type aware: it compresses what benefits from it and skips what does not — images, video, audio, fonts, archives and anything already compressed. min_size avoids spending CPU on payloads too small to gain.

ASGI / FastAPI

from b4n1_boost.middleware import FastAPIBoostCompressionMiddleware

app.add_middleware(FastAPIBoostCompressionMiddleware)

Streaming responses are compressed incrementally rather than buffered, so a large streamed response does not have to be materialized in memory first.

ETag / 304 caching

from b4n1_boost.middleware import ETagMiddleware

app.wsgi_app = ETagMiddleware(app.wsgi_app)

Clients that already hold a valid copy get 304 Not Modified and no body, saving both bandwidth and serialization work on repeat requests.

ASGI variant: ASGIETagMiddleware.

Security headers

from b4n1_boost.middleware import SecurityHeadersMiddleware

app.wsgi_app = SecurityHeadersMiddleware(app.wsgi_app)

Adds X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security, X-XSS-Protection and related headers.

ASGI variant: ASGISecurityHeadersMiddleware.

CORS

from b4n1_boost.middleware import CORSMiddleware

app.wsgi_app = CORSMiddleware(app.wsgi_app,
                              allow_origins=["https://example.com"])

ASGI variant: ASGICORSMiddleware.

Rate limiting

from b4n1_boost.middleware import RateLimitMiddleware

app.wsgi_app = RateLimitMiddleware(app.wsgi_app,
                                   max_requests=100,
                                   window_seconds=60)

Fixed-window limiting held in process. It is a guard against accidental abuse and hot loops, not a distributed quota — for limits that must hold across many processes, enforce them at the edge.

ASGI variant: ASGIRateLimitMiddleware.

Health check

from b4n1_boost.middleware import HealthCheckMiddleware

app.wsgi_app = HealthCheckMiddleware(app.wsgi_app, path="/health")
# GET /health -> 200 {"status": "ok"}

Answers without touching application code, which keeps a health probe from consuming a worker.

ASGI variant: ASGIHealthCheckMiddleware.

Response cache

from b4n1_boost.advanced import ResponseCache
from b4n1_boost.middleware import CacheMiddleware

cache = ResponseCache(max_size=1000, ttl_seconds=300)
app.wsgi_app = CacheMiddleware(app.wsgi_app, cache=cache)

max_size is a hard bound on entries held — the cache never grows without limit. Entries expire after ttl_seconds.

Request logging

from b4n1_boost.middleware import RequestLoggingMiddleware

app.wsgi_app = RequestLoggingMiddleware(app.wsgi_app)

ASGI variant: ASGIRequestLoggingMiddleware.

Decompression

from b4n1_boost.middleware import DecompressionMiddleware

app.wsgi_app = DecompressionMiddleware(app.wsgi_app)

Handles incoming Content-Encoding so endpoints can accept compressed request bodies.

Metrics

from b4n1_boost.middleware import CompressionMetrics, detect_proxy, metrics

CompressionMetrics tracks what was compressed and by how much, which is the fastest way to find out whether compression is earning its CPU time.

Proxy detection

from b4n1_boost.middleware import detect_proxy

Determines whether a reverse proxy is in front of the app, so headers such as X-Forwarded-For are only trusted when they came from one.

Ordering

Apply middleware in this order of intent:

1. Proxy / trust boundary — establish what headers you believe
2. Security headers — applied to every response
3. Rate limiting — reject early, before expensive work
4. Compression — last transform before bytes leave
5. ETag / cache — after the body is final

Reversing 4 and 5 produces incorrect ETags, because the validator would be computed over a body that no longer matches what the client receives.

See also

• Quick Start — the one-line installers
• Python SDK — utilities alongside the middleware

Background Tasks

Run heavy work off the request path without standing up a queue broker.

Why not a broker

A task queue is the right answer when work must survive a machine failure or be shared across many hosts. It is the wrong answer when the work is local, frequently, and a lost task costs a retry.

b4n1-boost targets the second case: work is handed to a worker thread immediately, and optionally journaled to disk so a restart can pick it up.

Python

from b4n1_boost import background, pending_tasks

@background
def build_report(user_id):
    # heavy work: render, aggregate, upload...
    return f"report-{user_id}"

handle = build_report(42)
result = handle.result()      # block only when you need the value

Crash recovery

from b4n1_boost import pending_tasks

pending = pending_tasks("./b4n1-tasks.jsonl")
for task in pending:
    ...   # re-run what a restart interrupted

When a journal path is configured, every submission is written before the task runs. A process restart therefore never silently loses a record.

Node.js

const { background, pendingTasks } = require('b4n1-boost/background');

const sendReport = background(async (userId) => {
  // build PDF, send email...
  return `report-${userId}`;
}, { journal: './b4n1-tasks.jsonl' });

const handle = sendReport(42);
const result = await handle;                     // wait when you need it
console.log(pendingTasks('./b4n1-tasks.jsonl')); // crash recovery

Returns in about a millisecond; the heavy work runs in a worker thread.

Worker-thread primitives

For single operations rather than whole functions:

from b4n1_boost import worker_compress, worker_decompress
from b4n1_boost import worker_minify, worker_jwt_validate, worker_shutdown

future = worker_compress(data, "zstd")
compressed = future.result()

When to reach for something else

Use an external queue instead when any of these hold:

• Tasks must survive losing the whole machine, not just the process
• More than one host needs to pull from the same queue
• You need delayed delivery, retries with backoff, or scheduled runs
• A lost task is unacceptable without a durable record elsewhere
• You need per-task visibility for operators

Journaling gives you restart safety on one host. It is not distributed coordination, and it does not pretend to be.

Graceful shutdown

Always stop the pool before the process exits, otherwise in-flight work can be cut mid-write:

from b4n1_boost import worker_shutdown

worker_shutdown()

Wire this to your framework’s shutdown hook — see the Django and FastAPI examples in the Python SDK.

See also

• Python SDK — where background and pending_tasks live
• Node.js SDK — the JavaScript surface

Django & DRF Accelerators

Two modules target the places Django spends the most time under load: bulk writes and serialization.

Django ORM accelerator

from b4n1_boost.django_accelerator import bulk_insert_native, FastModelMixin

bulk_insert_native(MyModel, [
    {"name": "Alice", "email": "alice@example.com"},
    {"name": "Bob",   "email": "bob@example.com"},
])

bulk_insert_native writes through PostgreSQL COPY instead of generating one INSERT statement per row. For bulk loads this is typically 5-10x faster than the ORM path.

When it helps

When not to use it

• The table has triggers or constraints that COPY bypasses or handles differently
• You depend on per-row save() overrides, signals or auto_now behaviour
• You need the objects back with their assigned primary keys

In those cases the ORM path is the correct one. COPY is a bulk transport, not a drop-in replacement for Model.save().

FastModelMixin

from b4n1_boost.django_accelerator import FastModelMixin

class MyModel(FastModelMixin, models.Model):
    class Meta:
        model = MyModel
        fields = ["id", "name"]

Mix into an existing model to gain the fast path without rewriting call sites.

DRF serializer accelerator

from b4n1_boost.drf_accelerator import fast_serialize, FastSerializerMixin

json_bytes = fast_serialize(queryset, fields=["id", "name", "email"])

Serializes a queryset straight to JSON without walking the serializer pipeline — typically 5-10x faster than the equivalent DRF serializer.

from b4n1_boost.drf_accelerator import FastSerializerMixin
from rest_framework import serializers

class MySerializer(FastSerializerMixin, serializers.ModelSerializer):
    class Meta:
        model = MyModel
        fields = ["id", "name"]

Existing serializers keep their class declaration and gain the fast path.

Trade-off

Fast serialization means fewer hooks. If a serializer relies on to_representation() overrides, per-field sources or custom nesting, verify the output matches byte for byte before switching — a serializer that is faster but emits different JSON is a bug, not an optimization.

A practical check:

slow = DefaultSerializer(queryset, many=True).data
fast = fast_serialize(queryset, fields=[...])
assert json.loads(slow) == json.loads(fast)

Applying both

import b4n1_boost

b4n1_boost.install_django()      # middleware: compression, ETag, headers...
# plus, in the views that write or read bulk data:
#   bulk_insert_native(...)      for writes
#   fast_serialize(...)          for list endpoints

List endpoints are usually where both meet: a paginated response pulls a queryset and serializes it on every request.

See also

• Python SDK — the rest of the API surface
• Middleware Reference — compression, caching and headers
• Performance — how the numbers were measured

Node.js SDK

npm install b4n1-boost

const B4N1Boost = require('b4n1-boost');

Platform support

The native core is bundled inside the package. There is no post-install download and no compiler requirement.

Checking that the native core loaded

B4N1Boost.isAvailable();   // true only when genuinely bound, not a fallback
B4N1Boost.libraryPath();   // absolute path of the binary actually loaded

isAvailable() is the JavaScript equivalent of Python’s status()["native_extension"]. Check it before you benchmark anything.

API

compressGzip(buffer, level = 4)

const gz = B4N1Boost.compressGzip(Buffer.from('hello'.repeat(1000)));

Falls back to zlib.gzipSync when the native core is unavailable, so this call always works.

compressZstd(buffer, level = 3)

const zst = B4N1Boost.compressZstd(payload);

Throws if the native core is unavailable — there is no pure-JS Zstd. Failing loudly here is deliberate: silently returning a different compression format would corrupt data expectations.

decompressZstd(buffer)

const raw = B4N1Boost.decompressZstd(zst);

Also throws when the native core is unavailable.

minifyHtml(htmlString)

B4N1Boost.minifyHtml('<p>  hi  </p>');

Falls back to whitespace collapsing without the native core.

isJsonValid(jsonString)

B4N1Boost.isJsonValid('{"a":1}');   // true

Falls back to JSON.parse in a try/catch.

Express middleware

const express = require('express');
require('b4n1-boost/express');

const app = express();
app.use(boostMiddleware());

The middleware handles compression and minification for you; see express.js in the package for the options it accepts.

Background tasks

const { background, pendingTasks } = require('b4n1-boost/background');

const sendReport = background(async (userId) => {
  return `report-${userId}`;
}, { journal: './b4n1-tasks.jsonl' });

const handle = sendReport(42);
const result = await handle;
console.log(pendingTasks('./b4n1-tasks.jsonl'));

Returns immediately; work runs in a worker thread. Every submission is journaled to disk, so a restart never loses a record. Full details in Background Tasks.

Testing

npm test

Runs a four-state matrix: valid input, invalid input, an expected entry that must be present, and an unknown entry that must be rejected. It must report 4/4.

Fallback behaviour summary

Nothing degrades silently into something that merely looks like success.

See also

• Introduction — what the shared core provides
• Status & Diagnostics — diagnosing a failed native load

.NET SDK

dotnet add package B4N1.Boost

Package ID: B4N1.Boost · NuGet.

Platform support

Native binaries are bundled for every supported runtime:

Compression

using B4N1.Boost;

byte[] gz  = NativeBoost.CompressGzipManaged(data, level: 4);
byte[] zst = NativeBoost.CompressZstdManaged(data, level: 3);

The Managed overloads take and return plain byte[] and handle allocation and freeing for you. The raw CompressGzip / CompressZstd P/Invoke signatures are also available if you are working with pinned buffers.

string compact = NativeBoost.MinifyHtmlManaged(html);
bool   ok      = NativeBoost.IsJsonValidManaged(json);

Response cache

using var cache = new NativeResponseCache(capacity: 1024);

cache.Set("GET:/users", body, status: 200, ttlSeconds: 300);

if (cache.Get("GET:/users") is (byte[] hit, ushort status))
{
    // serve directly
}

capacity is a hard bound — the cache never grows past it. Invalidate(key) removes a single entry, Clear() drops everything, and Dispose() releases the native handle.

cache.Invalidate("GET:/users");
cache.Clear();

Because the type implements IDisposable, prefer using or an explicit Dispose(). Leaked handles keep native memory alive past the request.

Bloom filter

using var bloom = new NativeBloomFilter(expectedItems: 10_000, fpRate: 0.01);

if (!bloom.CheckAndSet(item))
{
    // first time we have seen this item
}

CheckAndSet returns true if the item was already present, false if it was absent and has now been recorded. Size the filter with expectedItems up front: a filter sized for 100 items will produce false positives quickly under a real workload.

A Bloom filter can report that an item is present when it is not. It never reports an absent item as present. Use it to skip expensive work, not to decide correctness on its own.

Circuit breaker

using var breaker = new NativeCircuitBreaker(
    threshold: 5, successThreshold: 1, timeoutSeconds: 30);

if (breaker.Allows)
{
    try { CallDependency(); breaker.RecordSuccess(); }
    catch { breaker.RecordFailure(); }
}

After threshold consecutive failures the breaker stops allowing calls for timeoutSeconds. A success during the half-open probe reopens it.

Background tasks

var handle = Background.Run(() => BuildReport(userId), journal: "tasks.jsonl");

var result = handle.Result();          // blocking
var task    = handle.AsTask();         // or await it

Passing a journal path makes each submission durable across restarts. Background.PendingTasks(journal) returns what was interrupted, for replay.

ASP.NET middleware

app.UseMiddleware<BoostMiddleware>();

Applies compression and optional HTML minification. Constructor options: minifyHtml (default true) and gzipLevel (default 4).

Unload safety

Cache, Bloom filter and circuit breaker wrappers own native handles. Always dispose them — a long-running process that creates and abandons them will grow its native memory without bound.

See also

• Status & Diagnostics — verifying the native core
• Background Tasks — the shared task model

Java SDK

<dependency>
  <groupId>com.b4n1</groupId>
  <artifactId>boost</artifactId>
  <version>0.3.12</version>
</dependency>

Gradle:

implementation 'com.b4n1:boost:0.3.12'

Published on Maven Central as com.b4n1:boost.

Platform support

Native binaries ship inside the JAR under runtimes/ and are selected at load time from the OS and architecture.

Loading the native library

The static initializer picks the library for you:

// Explicit path (optional)
System.getenv("B4N1_BOOST_LIB_PATH");

When B4N1_BOOST_LIB_PATH is set, the file name is validated against the three accepted names — libb4n1_boost.so, libb4n1_boost.dylib, b4n1_boost.dll. Anything else is rejected with a SecurityException rather than loaded. That check exists so an unexpected file cannot be resolved into the JVM.

If the variable is unset, the library is resolved through the standard System.loadLibrary search path.

API

All methods are static on com.b4n1.boost.Boost:

import com.b4n1.boost.Boost;

byte[]  gz  = Boost.compressGzip(data, 4);
byte[]  zst = Boost.compressZstd(data, 3);
byte[]  raw = Boost.decompressZstd(zst);
String  min = Boost.minifyHtml(html);
boolean ok  = Boost.isJsonValid(json);

These are JNI calls: arguments are copied to native memory and results copied back. For tight loops, prefer fewer larger calls over many small ones — the marshalling cost per call can exceed the work for tiny payloads.

Response cache, Bloom filter, circuit breaker

import com.b4n1.boost.NativeResponseCache;
import com.b4n1.boost.NativeBloomFilter;
import com.b4n1.boost.NativeCircuitBreaker;

The three wrappers mirror the .NET API exactly:

try (var cache = new NativeResponseCache(1024)) {
    cache.set("GET:/users", body, (short) 200, 300);
    var hit = cache.get("GET:/users");
}

try (var bloom = new NativeBloomFilter(10_000L, 0.01)) {
    boolean alreadySeen = bloom.checkAndSet(item);
}

try (var breaker = new NativeCircuitBreaker(5, 1, 30L)) {
    if (breaker.allows()) { /* call */ }
}

All three are AutoCloseable, so use try-with-resources. Without it the native handle leaks until finalization — which may never run promptly enough in a busy process.

Background tasks

import com.b4n1.boost.Background;

var handle = Background.run(() -> buildReport(userId), "tasks.jsonl");
var result = handle.result();

Passing a journal path makes submissions durable across restarts.

Testing

mvn test

The suite covers the four-state matrix: valid input succeeds, invalid input fails with a typed error, an expected entry missing is caught, and an unknown entry is rejected.

See also

• .NET SDK — the same wrappers for .NET
• Status & Diagnostics — diagnosing a failed native load

Go SDK

A small, dependency-free wrapper over the shared native core.

import "github.com/B4N1-com/b4n1-boost/polyglot/go"

API

Four functions, all in the package root:

package main

import (
    "fmt"

    boost "github.com/B4N1-com/b4n1-boost/polyglot/go"
)

func main() {
    gz, err := boost.CompressGzip(data, 4)
    if err != nil {
        // handle
    }

    zst, err := boost.CompressZstd(data, 3)
    if err != nil {
        // handle
    }

    html := boost.MinifyHTML(rawHTML)

    ok := boost.IsJSONValid(body)
    fmt.Println(ok)
}

Error handling

Both compression functions return ([]byte, error) rather than panicking. A failure inside the native core — an invalid level, an allocation problem — surfaces as an ordinary Go error, so callers can handle it without recovering from a panic.

MinifyHTML and IsJSONValid return values directly because they have no meaningful failure mode at this layer: an unminifiable document returns unchanged, and an invalid JSON string returns false.

Levels

Levels outside the valid range produce an error rather than being clamped silently — a caller who asks for level 99 has a bug worth surfacing.

Testing

go test ./...

The test file encodes the four-state matrix as TestState1ExistsAndCorrect, TestState2ExistsAndIncorrect, TestState3ShouldExistAndMissing and TestState4ShouldNotExistAndCorrectlyAbsent, so a regression in any of the four shows up by name.

Design notes

• Plain Go types at the boundary. Callers work with ordinary []byte and string values; marshalling happens inside the wrapper.
• No hidden global state. Each call is independent, so the package is safe for concurrent use from multiple goroutines.
• Errors, not panics. Native failures become Go errors.

See also

• PHP SDK and Ruby SDK — the other thin wrappers
• Status & Diagnostics — verifying the core loaded

PHP SDK

composer require b4n1/boost

API

Static methods on the Boost class:

use B4N1\Boost\Boost;

$gz   = Boost::compressGzip($data, 4);
$zst  = Boost::compressZstd($data, 3);
$html = Boost::minifyHtml($rawHtml);
$ok   = Boost::isJsonValid($json);

The extension is loaded lazily on first use — there is no manual bootstrap call to remember.

Middleware

use B4N1\Boost\Middleware\BoostMiddleware;

$app->add(new BoostMiddleware(minifyHtml: true, gzipLevel: 4));

The middleware compresses outgoing responses and optionally minifies HTML, following the PSR-15 request/response flow.

$middleware = new BoostMiddleware(
    minifyHtml: true,
    gzipLevel: 4,
);

$response = $middleware->handle($request, $next);

Options

Set minifyHtml to false when responses already arrive minified, or when the body is not HTML at all — re-minifying JSON or a binary stream wastes CPU and can corrupt payloads that are not markup.

Testing

php test.php

Covers the four-state matrix: valid input, invalid input, an expected entry that must be present, and an unknown entry that must be rejected.

See also

• Ruby SDK — the equivalent Rack integration
• Go SDK — the same core from Go

Ruby SDK

gem install b4n1-boost

API

Class methods under the B4N1 module namespace:

require 'b4n1_boost'

gz   = B4N1::Boost.compress_gzip(data, level: 4)
zst  = B4N1::Boost.compress_zstd(data, level: 3)
html = B4N1::Boost.minify_html(raw_html)
ok   = B4N1::Boost.json_valid?(json)

The trailing ? on json_valid? follows Ruby convention: the method returns a boolean and is safe to use in a conditional.

Rack middleware

require 'b4n1_boost/rack'

use B4N1::Boost::RackMiddleware
run MyApp

Insert it with use rather than wrapping the application manually — Rack orders middleware outermost-first, and compression belongs near the outside of the stack so it applies to everything below it.

use B4N1::Boost::RackMiddleware, minify_html: true, gzip_level: 4

Turn minify_html off for non-HTML responses; minifying something that is not markup wastes CPU and gains nothing.

Concurrency

Each call is independent and holds no shared mutable state, so it is safe to call from multiple threads. Nothing needs a global lock around it.

Testing

ruby test.rb

Covers the four-state matrix: valid input, invalid input, an expected entry that must be present, and an unknown entry that must be rejected.

See also

• PHP SDK — the equivalent Composer integration
• Middleware Reference — the Python middleware stack

Status & Diagnostics

Before you benchmark, migrate or file a performance bug, confirm what is actually running. Most “it isn’t faster” reports turn out to be a fallback path that was never replaced.

The one call that answers everything

import b4n1_boost

print(b4n1_boost.status())

{
    "native_extension": True,
    "version": "0.3.12",
    "features": {
        "json_acceleration": True,
        "json_canonicalize": True,
        "compression": ["gzip", "brotli", "zstd"],
        "middleware": ["django", "fastapi", "flask"],
    },
    "compression_engines": {
        "gzip": True,
        "brotli": True,
        "zstd": True,
    },
}

If native_extension is False, stop. Every performance figure in Performance is measured against the native core and does not apply to a fallback.

Diagnosing a failed load

Work through these in order:

1. Confirm the wheel matched your platform

pip show b4n1-boost
python -c "import sys; print(sys.version)"

The requirement is >=3.10. A platform without a published wheel will not have a native core to load.

2. Confirm the extension file exists

python -c "import b4n1_boost, pathlib; p = pathlib.Path(b4n1_boost.__file__).parent; print(p); print(list(p.glob('_core*')))"

An empty list means the package installed without its native module — usually a truncated download or an interrupted install. Reinstall:

pip install --force-reinstall --no-cache-dir b4n1-boost

3. Import it directly to surface the real error

python -c "import b4n1_boost._core"

An import error here prints the underlying cause, which is far more useful than a native_extension: False summary.

4. Check for a stale copy

python -c "import b4n1_boost; print(b4n1_boost.__file__)"

A path outside the current virtual environment means an older global install is shadowing the one you think you are testing.

5. Verify after any upgrade

import b4n1_boost
assert b4n1_boost.status()["native_extension"] is True
assert b4n1_boost.__version__ == "0.3.12"

A cached extension from a previous version is a common source of confusing results.

Per-SDK availability checks

Node’s libraryPath() is particularly useful when more than one copy of the package is installed: it names the exact binary in use, so you can tell whether you are loading the one you edited.

Health check as a runtime probe

from b4n1_boost.middleware import HealthCheckMiddleware

app.wsgi_app = HealthCheckMiddleware(app.wsgi_app, path="/health")

curl -i http://localhost:8000/health
# HTTP/1.1 200 OK
# {"status": "ok"}

Wire this to your process supervisor. A 200 confirms the app is serving; it does not confirm the native core loaded — pair it with status() at startup if you want that assertion too.

Assert at startup, not in production

Fail loudly the moment the core is missing, rather than discovering it under load:

import b4n1_boost

if not b4n1_boost.status()["native_extension"]:
    raise RuntimeError("b4n1-boost native core failed to load")

This is the difference between a deploy that fails immediately and one that runs for a week at half speed.

Reporting a problem

Include all of the following — it is the difference between a one-reply fix and a week of questions:

1. b4n1_boost.status() output, verbatim
2. Python version and operating system / architecture
3. Output of pip show b4n1-boost
4. Output of python -c "import b4n1_boost._core" if it fails
5. The command you ran and what you expected

See also

• Installation — platform and version support
• Performance — what the numbers assume
• FAQ — common questions

Frequently Asked Questions

Does it really work without changing my code?

Yes. install_django(), install_fastapi(app) and install_flask(app) wire middleware around your application. Views, templates, models and serializers stay as they are.

The two exceptions are the accelerators, which you opt into explicitly: Django & DRF Accelerators replace a specific call site (bulk_insert_native, fast_serialize) because they produce the same result by a different route.

Do I need to compile anything?

No. Wheels are precompiled for Linux (x86_64, aarch64), macOS (x86_64, arm64) and Windows x86_64. pip install b4n1-boost is the whole step — no compiler, no build backend, no system libraries.

How do I know it actually loaded?

import b4n1_boost
assert b4n1_boost.status()["native_extension"] is True

Do this before benchmarking. See Status & Diagnostics.

Do I need Redis or a broker?

No, for background tasks. Work is dispatched to a worker thread with optional disk journaling.

You should still use a real queue when tasks must survive losing the machine, be shared across hosts, or need scheduled delivery. Journaling gives restart safety on one host — it is not distributed coordination.

Which compression algorithm should I use?

For static files, compress_static_dir skips already-compressed formats (images, video, audio, fonts, archives) automatically.

Will it help if my app is not CPU-bound?

Probably not. b4n1-boost removes CPU time spent on serialization, compression and static assets. If your bottleneck is database latency, network I/O or an external API, the headroom is elsewhere.

Measure first: if run_benchmarks() shows no meaningful gap against the standard library on your payloads, there is nothing to gain.

Is it safe to run behind a reverse proxy?

Yes. detect_proxy() determines whether a proxy is in front of the app so headers like X-Forwarded-For are only trusted when they came from one.

from b4n1_boost.middleware import detect_proxy

Never trust forwarded headers unconditionally — a client can forge them.

Does it support async frameworks?

Yes. Every middleware has an ASGI variant (ASGIETagMiddleware, ASGICORSMiddleware, ASGISecurityHeadersMiddleware, ASGIRateLimitMiddleware, ASGIHealthCheckMiddleware, ASGIRequestLoggingMiddleware, FastAPIBoostCompressionMiddleware), and compression streams responses rather than buffering them.

Can I use only part of it?

Yes. The pieces are independent — compression, ETag, security headers, CORS, rate limiting, health check and the utilities can each be used alone. boost_all() installs the common set in one call; individual middleware can be added by hand when you want a different configuration.

What happens on an unsupported platform?

The Python package falls back to a pure-Python path: correct output, no native speed. Node.js does the same, except for compressZstd and decompressZstd, which throw rather than silently producing a different format.

Check status()["native_extension"] (Python) or isAvailable() (Node) to know which path you are on.

What is the difference between dumps and dumps_direct?

batch_dumps is where the largest wins appear for list-shaped workloads, because per-call overhead is paid once instead of N times.

Which license applies?

The SDK wrapper source is Business Source License 1.1 (BUSL-1.1). The precompiled native binaries are covered by a separate EULA.txt that ships inside each artifact.

Production use is free for organizations with total annual gross revenue up to USD $100,000. Above that, or for reselling it as a managed service, a commercial license is required.

Where do I report bugs?

Open an issue on github.com/B4N1-com/b4n1-boost. Include the diagnostic output listed in Status & Diagnostics — status, Python version, OS/architecture and the exact failing command.

See also

• Quick Start
• Performance
• License

Changelog

Notable changes per release, following Keep a Changelog and Semantic Versioning.

The full detail lives in CHANGELOG.md in the repository. This page is the curated view.

[0.3.12] — current

Fourth registry released: the Java SDK is now on Maven Central as com.b4n1:boost, alongside PyPI, npm and NuGet. Release verification suite: 38 checks passing.

[0.3.11]

Packaging and record-correctness fixes across the published artifacts: wheel metadata now matches its archive contents exactly, so registries accept uploads without post-hoc warnings.

[0.3.0] — 2026-09-01

The middleware and accelerator release.

Added

Middleware

• SecurityHeadersMiddleware — X-Content-Type-Options, X-Frame-Options, Strict-Transport-Security, X-XSS-Protection, Referrer-Policy, Permissions-Policy
• CORSMiddleware with configurable origins, methods and headers
• HealthCheckMiddleware — GET /health returns 200 JSON
• DecompressionMiddleware — accepts gzip/brotli/zstd request bodies
• CacheMiddleware backed by ResponseCache (LRU + TTL)
• RequestLoggingMiddleware and its ASGI variant
• ETagMiddleware with 304 handling
• RateLimitMiddleware — token bucket per client IP
• Content-Type aware compression
• CompressionMetrics — bytes in/out, request count, ratio
• detect_proxy() — forwarded-header trust detection
• boost_all() — install the common set in one call

Acceleration

• NativeJson.batch_dumps() — N serializations in a single lock acquire
• Worker thread for compression, minification and JWT — heavy work off the calling thread
• fast_serialize() + FastSerializerMixin — 5-10x faster queryset → JSON
• bulk_insert_native() (PostgreSQL COPY) + FastModelMixin — 5-10x faster bulk writes
• html_to_markdown() — HTML to clean Markdown for LLM consumption
• minify_html(), minify_css(), minify_js()
• JWT validation with an HMAC-SHA256/512 path and a fallback
• ResponseCache (LRU, TTL), BloomRateLimiter, CircuitBreaker
• compress_static_file() / compress_static_dir()
• Telemetry bindings: init, capture_error, log_info, log_phase, flush

Changed

• JSON path moved to a substantially faster backend — 10.5x over json.dumps on medium payloads
• Middleware refactored onto unified WSGI/ASGI base classes

Fixed

• Middleware installs are idempotent — a double install no longer stacks duplicates
• Native JSON path used directly in middleware, removing an intermediate conversion
• README installation URL

[0.2.0] — 2026-08-28

Added

• Zstd compression — 28x faster than stdlib gzip
• Content-Type aware middleware
• ETag generation and 304 caching
• Rate limiting (token bucket)
• Proxy detection headers
• Compression metrics collection

Changed

• Improved middleware architecture

[0.1.0]

Initial release: native JSON serialization, gzip/brotli compression, and the Django / FastAPI / Flask installers.

See also

• Status & Diagnostics — how to check your installed version
• License

License

b4n1-boost uses a dual-layer license. Two artifacts, two instruments — read both before you distribute anything.

1. SDK wrapper source — Business Source License 1.1

The per-language SDK wrappers (the thin bindings for Python, Node.js, .NET, Java, Go, PHP and Ruby) are licensed under Business Source License 1.1 (BUSL-1.1), with the full text in LICENSE at the repository root.

Parameters

What that means in practice

• You may use it in production for free if your organization’s total annual gross revenue is at or below USD $100,000.
• Above that threshold, or if you want to resell or provide b4n1-boost as a managed commercial service, you need a commercial license from the Licensor.
• On the Change Date, the Licensed Work converts to the Apache License 2.0 and becomes openly licensed.
• You may study and modify the source for any purpose; the production restriction above is the binding term.

BUSL-1.1 is the correct SPDX identifier for Business Source License 1.1. Note that BSL-1.1 in SPDX denotes an unrelated permissive license — always check which one a manifest actually declares.

2. Native binaries — End User License Agreement

The precompiled native binaries are licensed separately under a EULA that ships inside every binary artifact:

• the compiled native libraries (libb4n1_boost.so, b4n1_boost.dylib, b4n1_boost.dll)
• the packaged per-language bindings (*.node, *.jar, *.nupkg, *.gem, *.phar, platform wheels)
• the b4n1-boost standalone executable

The EULA.txt travels with each artifact — a wheel, npm tarball, NuGet package, Maven artifact or gem each carry their own copy. There is no separate download step, and an artifact without its EULA is incomplete.

3. Combining the two

Any redistribution must keep both documents intact, together with all copyright and trademark notices. Removing or altering the license metadata of a published artifact is not permitted.

4. Trademarks

“Business Source License” is a trademark of MariaDB Corporation Ab; the license text is copyright (c) 2017 MariaDB Corporation Ab, All Rights Reserved, and is used here under its published terms. The B4N1 name, logos and marks remain the property of B4N1.

5. No warranty

Both instruments are 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 non-infringement. In no event shall the Licensor be liable for any claim, damages or other liability arising from use of the software.

Commercial licensing

For licensing terms beyond the Additional Use Grant — enterprise deployment, managed service delivery, or redistribution arrangements — contact dev@b4n1.com.

See also

• Introduction
• Installation
• Changelog