npm package: @nightnetwork/reflux
Description: Reflux is a simple middleware that sits at the transport level, it allows for things like request/response manipulation. along with web sockets.
Author: Night Network
Latest version: 2.2.0

# 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

```bash
npm install @nightnetwork/reflux
```

## Usage Modes

Reflux can be used in three ways:

### 1. Standalone Transport

Use Reflux as a direct BareMux transport:

```javascript
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:

```javascript
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:

```javascript
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)

```javascript
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

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

const api = new RefluxAPI();
```

## API Methods

### Plugin Management

```javascript
// 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

```javascript
// 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](./docs/README.md)**

- [Getting Started](./docs/getting-started.md) - Setup and first plugin
- [HTML Modification](./docs/html-modification.md) - Modify website content
- [WebSocket Middleware](./docs/websocket-middleware.md) - Intercept WebSocket traffic
- [Request/Response Middleware](./docs/request-response-middleware.md) - HTTP interception
- [Plugin System](./docs/plugin-system.md) - Plugin architecture deep dive
- [API Reference](./docs/api-reference.md) - Complete API docs
- [Examples](./docs/examples.md) - 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](./LICENSE) file for details.

## Contributing

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

## Links

- [Documentation](./docs/README.md)
- [GitHub Repository](https://github.com/Obsidian-Dev-Labs/Reflux)
- [NPM Package](https://www.npmjs.com/package/@nightnetwork/reflux)