Reflux

Reflux is a powerful, universal request/response middleware engine designed for any BareMux compatible web proxy. It features a dynamic plugin system that allows you to load and execute custom JavaScript code on specific websites.

Features

• Dynamic Plugin System: Load and execute custom plugins on specific sites or globally
• Request/Response Middleware: Intercept and modify HTTP requests and responses
• WebSocket Support: Middleware support for WebSocket connections
• Site-Specific Targeting: Run plugins only on specified domains with pattern matching
• Real-time Control: Add, remove, and manage plugins dynamically
• Dual Mode: Works as standalone transport OR as Enigma module

Installation

npm install @nightnetwork/reflux

Usage Modes

Reflux can be used in three ways:

1. Standalone Transport

Use Reflux as a direct BareMux transport:

import { BareMuxConnection } from "@mercuryworkshop/bare-mux";

const connection = new BareMuxConnection("/baremux/worker.js");

await connection.setTransport("/reflux/index.mjs", [{
  base: "/epoxy/index.mjs",
  wisp: "wss://example.com/wisp/"
}]);

2. Enigma Module

Use Reflux as an Enigma module alongside other modules:

import { BareMuxConnection } from "@mercuryworkshop/bare-mux";

const connection = new BareMuxConnection("/baremux/worker.js");

await connection.setTransport("/enigma/index.mjs", {
  base: "/epoxy/index.mjs",
  wisp: "wss://example.com/wisp/",
  modules: [
    "/reflux/module.mjs",
    "/oxygen-module/index.mjs"
  ]
});

3. RefluxPath (Legacy)

Import from the path export for bare-mux compatibility:

import { BareMuxConnection } from "@mercuryworkshop/bare-mux";

const connection = new BareMuxConnection("/baremux/worker.js");

await connection.setTransport("/reflux/lib/index.cjs", [{
  base: "/epoxy/index.mjs",
  wisp: "wss://example.com/wisp/"
}]);

Reflux API

The Reflux API allows you to manage plugins from your application code:

ESM Import (Recommended)

import { RefluxAPI } from "@nightnetwork/reflux/api";

const api = new RefluxAPI();

await api.addPlugin({
  name: "my-plugin",
  sites: ["example.com"],
  function: `
    /* @browser */
    console.log('Plugin running on:', url);
    /* @/browser */
  `
});

await api.enablePlugin("my-plugin");

Direct Import

import { RefluxAPI } from "@nightnetwork/reflux";

const api = new RefluxAPI();

API Methods

Plugin Management

// Add a plugin
await api.addPlugin({
  name: string,
  sites: string[] | ['*'],  // ['*'] for all sites
  function: string          // JavaScript code to execute
});

// Remove a plugin
await api.removePlugin(name: string);

// Enable/disable plugins
await api.enablePlugin(name: string);
await api.disablePlugin(name: string);

// List all plugins
const plugins = await api.listPlugins();
// Returns: Array<{ name, sites, enabled, function }>

// Get enabled plugins only
const enabled = await api.getEnabledPlugins();
// Returns: string[]

// Update plugin sites
await api.updatePluginSites(name: string, sites: string[]);

Package Exports

// Main transport
import RefluxTransport from "@nightnetwork/reflux";
import RefluxTransport from "@nightnetwork/reflux/transport";

// API (recommended)
import { RefluxAPI } from "@nightnetwork/reflux/api";

// Legacy path export
import RefluxTransport from "@nightnetwork/reflux/path";

// Enigma module
import createRefluxModule from "@nightnetwork/reflux/module";

Documentation

📚 Complete Documentation

• Getting Started - Setup and first plugin
• HTML Modification - Modify website content
• WebSocket Middleware - Intercept WebSocket traffic
• Request/Response Middleware - HTTP interception
• Plugin System - Plugin architecture deep dive
• API Reference - Complete API docs
• Examples - Working code examples

Use Cases

• HTML Modification: Inject scripts, modify content, add custom UI
• Request Interception: Modify headers, URLs, request bodies
• Response Transformation: Transform API responses, filter content
• WebSocket Monitoring: Log and modify WebSocket messages
• Ad Blocking: Remove unwanted elements and content
• Custom Analytics: Track user behavior and page performance
• Security Enhancements: Add CSP headers, sanitize content
• Dark Mode: Apply custom themes to any website

Architecture

Standalone Transport Mode

┌─────────────────┐
│   Application   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    BareMux      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│     Reflux      │ ◄── Plugin System
│   Transport     │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Base Transport  │
│ (Epoxy/Libcurl) │
└─────────────────┘

Enigma Module Mode

┌─────────────────┐
│   Application   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│    BareMux      │
└────────┬────────┘
         │
         ▼
┌─────────────────────────────────┐
│          Enigma                 │
│  ┌─────────────────────────┐   │
│  │  Reflux Module          │   │ ◄── Plugin System
│  │  + Other Modules        │   │
│  └─────────────────────────┘   │
└────────┬────────────────────────┘
         │
         ▼
┌─────────────────┐
│ Base Transport  │
│ (Epoxy/Libcurl) │
└─────────────────┘

│ Middleware │ └────────┬────────┘ │ ▼ ┌─────────────────┐ │ Base Transport │ │ (Epoxy/Libcurl) │ └─────────────────┘

## Development

This repository uses Bun, but any package manager will work.

```bash
# Install Bun 
curl -fsSl https://bun.sh/install | bash # Linux/macOS
powershell -c "irm bun.sh/install.ps1 | iex" # Windows

# Clone the repository
git clone https://github.com/Obsidian-Dev-Labs/Reflux.git
cd Reflux

# Install dependencies
bun install

# Run the demo
bun demo

License

See LICENSE file for details.

Contributing

Contributions are welcome! Please read the documentation before submitting pull requests.

Links

• Documentation
• GitHub Repository
• NPM Package