Skip to content

README.md

Latest commit

 

History

History
271 lines (205 loc) · 7.4 KB

README.md

File metadata and controls

271 lines (205 loc) · 7.4 KB

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

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