diff --git a/astro.config.ts b/astro.config.ts index 4cb73e5..ba44445 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -57,18 +57,18 @@ export default defineConfig({ ], plugins: [ starlightAutoSidebar(), - starlightTypeDoc({ - entryPoints: ["./typedoc-repos/scramjet/src/entry.ts"], - tsconfig: "./tsconfig-scramjet.json", - sidebar: { - label: "Scramjet API", - }, - typeDoc: { - skipErrorChecking: true, - excludeNotDocumented: false, - treatWarningsAsErrors: false, - }, - }), + // starlightTypeDoc({ + // entryPoints: ["./typedoc-repos/scramjet/src/entry.ts"], + // tsconfig: "./tsconfig-scramjet.json", + // sidebar: { + // label: "Scramjet API", + // }, + // typeDoc: { + // skipErrorChecking: true, + // excludeNotDocumented: false, + // treatWarningsAsErrors: false, + // }, + // }), ], components: { Head: "./src/components/MetadataHead.astro", @@ -93,7 +93,6 @@ export default defineConfig({ "proxies/scramjet", "proxies/rammerhead", "proxies/ultraviolet", - typeDocSidebarGroup, ], }, { diff --git a/src/content/docs/organizations/night-network.mdx b/src/content/docs/organizations/night-network.mdx index e142832..da7e1fb 100644 --- a/src/content/docs/organizations/night-network.mdx +++ b/src/content/docs/organizations/night-network.mdx @@ -25,4 +25,3 @@ Night Network is an organization of developers focused on creating innovative mi # Relations to TN Night Network is an organization partnered with TN because of its community and large userbase of 2M+ active users. - diff --git a/src/content/docs/reference/documentation-standards.mdx b/src/content/docs/reference/documentation-standards.mdx index 25d0379..e4fe305 100644 --- a/src/content/docs/reference/documentation-standards.mdx +++ b/src/content/docs/reference/documentation-standards.mdx @@ -11,6 +11,7 @@ This document outlines the writing standards and formatting conventions used thr All MDX files use YAML frontmatter for metadata: ## Basic Page Frontmatter + ```yaml --- title: Page Title @@ -20,6 +21,7 @@ keywords: ["keyword1", "keyword2", "keyword3"] ``` ## Proxy/Technology/Transport Pages + ```yaml --- title: Project Name @@ -33,6 +35,7 @@ order: 1 # Optional: sidebar ordering ``` ## Organization Pages + ```yaml --- title: Organization Name @@ -47,23 +50,27 @@ official-link: "https://example.com" # Writing Style ## Tone + - **Professional but approachable** - **Clear and concise** - **Technically accurate** - **Community-focused** ## Voice + - Use active voice: "Scramjet provides" not "is provided by" - Direct address: "You can install" not "One can install" - Present tense for current features - Be specific, not vague ## Technical Terms + - **First mention**: Full name with abbreviation in parentheses - **Subsequent mentions**: Use abbreviation or short form - **Example**: "Service Worker (SW)" → later use "SW" ### Example from Scramjet docs: + > "In the proxy community, you may see it abbreviated as 'SJ'." # Structure Patterns @@ -71,29 +78,34 @@ official-link: "https://example.com" ## Page Organization ### 1. Opening Section + - Brief description (1-2 sentences) - Key features or value proposition - Context about the project's role ### 2. Feature List + Use bullet points with **bold headings**: + ```markdown - **Feature Name**: Brief description - **Another Feature**: Brief description ``` ### 3. Installation/Setup -```markdown + +````markdown # Installation ```bash npm install package-name -``` +```` ## Dependencies List required packages... -``` + +```` ### 4. Usage Examples - Start simple, progress to complex @@ -118,9 +130,10 @@ End with links to: ## H2: Major Sections ### H3: Subsections #### H4: Detailed Breakdowns -``` +```` **Rules:** + - Only one H1 per page (the title) - Don't skip heading levels - Keep headings concise (3-7 words) @@ -129,18 +142,22 @@ End with links to: # Code Examples ## Inline Code + Use backticks for: + - File names: `package.json` - Function names: `setTransport()` - Variable names: `connection` - Short code snippets: `const api = new API()` ### Example: + > The class `Person` is in `src/models/person.ts`. ## Code Blocks ### With Language Identifier + ````markdown ```javascript const example = "code"; @@ -148,6 +165,7 @@ const example = "code"; ```` ### With Highlighting + ````markdown ```js import { scramjetPath } from "@mercuryworkshop/scramjet/path"{:js} @@ -155,6 +173,7 @@ import { scramjetPath } from "@mercuryworkshop/scramjet/path"{:js} ```` ### Shell Commands + ````markdown ```bash npm install package-name @@ -181,7 +200,9 @@ importScripts("/scram/scramjet.all.js"); # Admonitions (Callout Boxes) ## Note + For general information or tips: + ```markdown :::note In the proxy community, you may see it abbreviated as "SJ". @@ -189,7 +210,9 @@ In the proxy community, you may see it abbreviated as "SJ". ``` ## Caution/Warning + For important warnings: + ```markdown :::caution Fixed types haven't landed in the NPM package yet. @@ -197,6 +220,7 @@ Fixed types haven't landed in the NPM package yet. ``` ## Note with Title + ```markdown :::note[Custom Title] Content goes here. @@ -204,6 +228,7 @@ Content goes here. ``` ## When to Use + - **Note**: Non-critical information, helpful tips - **Caution**: Important limitations or gotchas - **Warning**: Critical issues that could cause problems @@ -212,24 +237,28 @@ Content goes here. # Links ## Internal Links (Same Site) + ```markdown [**Scramjet**](../proxies/scramjet.mdx) [transport guide](../transports/using-transports.mdx) ``` **Pattern:** + - Use relative paths - Include `.mdx` extension - Use `../` to go up directories - Bold important project names ## External Links + ```markdown [GitHub Repository](https://github.com/org/repo) [Official Documentation](https://example.com/docs) ``` ## Link in Lists + ```markdown - [**Project Name**](../category/project.mdx) - Brief description ``` @@ -237,6 +266,7 @@ Content goes here. # Lists ## Unordered Lists + ```markdown - Item one - Item two @@ -246,6 +276,7 @@ Content goes here. ``` ## Ordered Lists + ```markdown 1. First step 2. Second step @@ -253,6 +284,7 @@ Content goes here. ``` ## Definition Lists + ```markdown - **Term**: Definition or explanation - **Another Term**: Another definition @@ -261,16 +293,19 @@ Content goes here. # Images ## With Alt Text + ```markdown ![Official Logo](https://example.com/logo.png) ``` ## With Sizing + ```markdown ... ``` ## Placeholder Images + ```markdown ![Placeholder](https://via.placeholder.com/800x200/1a1a2e/eee?text=Text) ``` @@ -291,26 +326,31 @@ Use Markdown tables for structured data: ## API Methods ### Method Signature -```markdown + +````markdown ### methodName() ```typescript async methodName(param: Type): Promise -``` +```` Brief description. **Parameters:** + - `param` (Type): Description **Returns:** + - `Promise` - Description **Example:** + ```javascript const result = await api.methodName(value); ``` -``` + +```` ## Interface Documentation ```markdown @@ -320,40 +360,48 @@ interface InterfaceName { property: string; optional?: number; } -``` -``` +```` + +```` ## Configuration Options ```markdown **Options:** - `option1` (type): Description (default: value) - `option2` (type): Description -``` +```` # Formatting Best Practices ## Emphasis ### Bold + Use for: + - **Feature names** - **Important terms** on first use - **Key concepts** - **Section emphasis** ### Italic + Use sparingly for: + - *Emphasis within a sentence* - *Book/document titles* ### Bold + Italic -Use very rarely for **_critical warnings_** + +Use very rarely for ***critical warnings*** ## Lists vs. Paragraphs + - Use lists for: Multiple related items, steps, options - Use paragraphs for: Explanations, descriptions, narrative ## Code vs. Text + - Use code formatting for anything a user would type or see in code - Use regular text for concepts and explanations @@ -392,7 +440,7 @@ History and relationship to TitaniumNetwork... ## Transport Page Pattern -```markdown +````markdown --- title: Transport Name description: Brief description @@ -411,20 +459,23 @@ Introduction paragraph. ```bash npm install ... -``` +```` # Usage ## Basic Usage + Code example... ## Advanced Usage + Code example... # Related Projects Links... -``` + +```` ## Reference Page Pattern @@ -446,22 +497,24 @@ Content... ## Subtopic Content... -``` +```` # Common Phrases and Patterns ## Installation -```markdown + +````markdown # Installation ```bash npm install package-name -``` +```` ## Dependencies Requires the following peer dependencies: -``` + +```` ## Usage Introduction ```markdown @@ -469,8 +522,9 @@ Here is a basic example of using [Project]: ```javascript // code -``` -``` +```` + +```` ## Method Documentation ```markdown @@ -484,8 +538,9 @@ Description. **Example:** ```javascript code example -``` -``` +```` + +```` ## Troubleshooting ```markdown @@ -499,7 +554,7 @@ code example 1. Step one 2. Step two -``` +```` # Consistency Checklist @@ -533,6 +588,7 @@ Refer to these pages as examples: # Quick Reference ## File Structure + ``` --- title: ... @@ -555,6 +611,7 @@ Content ``` ## Common Admonitions + ```markdown :::note Informational content @@ -566,6 +623,7 @@ Warning content ``` ## Code Block + ````markdown ```language code here @@ -573,6 +631,7 @@ code here ```` ## Internal Link + ```markdown [**Project Name**](../category/file.mdx) ``` diff --git a/src/content/docs/reference/transport-development-standards.mdx b/src/content/docs/reference/transport-development-standards.mdx index 1d7310b..0b07958 100644 --- a/src/content/docs/reference/transport-development-standards.mdx +++ b/src/content/docs/reference/transport-development-standards.mdx @@ -13,13 +13,17 @@ A transport is a module that implements the `BareTransport` interface from [bare ## Transport Types ### Traditional Transports + Directly handle network requests using specific protocols (e.g., Wisp, Bare): + - **EpoxyTransport**: Uses epoxy-tls for encrypted communication - **CurlTransport**: Uses libcurl.js for TLS-encrypted requests - **Bare-Client**: Implements the Bare protocol ### Middleware Transports + Wrap other transports to add functionality: + - **Reflux**: Adds middleware and plugin capabilities to any base transport # Core Interface Requirements @@ -72,6 +76,7 @@ export default class MyTransport implements BareTransport { ``` ### Example: EpoxyTransport + ```typescript export default class EpoxyTransport implements BareTransport { ready = false; @@ -88,6 +93,7 @@ export default class EpoxyTransport implements BareTransport { ``` ### Example: CurlTransport + ```typescript export default class LibcurlClient implements BareTransport { wisp: string; @@ -110,12 +116,14 @@ export default class LibcurlClient implements BareTransport { ## 2. Initialization Pattern The `init()` method should: + - Load any required libraries/WebAssembly modules - Set up connections or sessions - Set `ready` to `true` when complete - Handle errors gracefully with logging ### Example: CurlTransport + ```typescript async init() { if (this.transport) @@ -143,6 +151,7 @@ async init() { ``` ### Example: EpoxyTransport + ```typescript async init() { await initEpoxy(); // Load WASM module @@ -157,6 +166,7 @@ async init() { ``` ### Example: Reflux (Middleware Transport) + ```typescript async init() { const { @@ -192,6 +202,7 @@ async init() { ## 3. Request Handling The `request()` method should: + - Handle all HTTP methods (GET, POST, PUT, DELETE, etc.) - Support request bodies of various types - Respect abort signals @@ -199,6 +210,7 @@ The `request()` method should: - Handle redirects appropriately (typically `redirect: "manual"`) ### Example: EpoxyTransport + ```typescript async request( remote: URL, @@ -232,6 +244,7 @@ async request( ``` ### Example: CurlTransport + ```typescript async request( remote: URL, @@ -270,6 +283,7 @@ async request( ## 4. WebSocket Handling The `connect()` method should: + - Establish WebSocket connections - Support protocol negotiation - Handle binary and text messages @@ -277,6 +291,7 @@ The `connect()` method should: - Set appropriate `binaryType` (typically "arraybuffer") ### Example: EpoxyTransport + ```typescript connect( url: URL, @@ -315,6 +330,7 @@ connect( ``` ### Example: CurlTransport + ```typescript connect( url: URL, @@ -366,6 +382,7 @@ async meta() { ## Error Handling **Do:** + - ✅ Validate options in constructor - ✅ Throw descriptive errors for invalid configurations - ✅ Log errors with context @@ -373,6 +390,7 @@ async meta() { - ✅ Respect abort signals **Example:** + ```typescript constructor(options) { if (!options.wisp.endsWith("/")) { @@ -405,6 +423,7 @@ console.debug('%cRF%c Initializing transport wrapper', ## Type Safety **Do:** + - ✅ Use TypeScript for type safety - ✅ Define clear option interfaces - ✅ Import types from bare-mux @@ -427,6 +446,7 @@ export type MyTransportOptions = { ## Options Handling **Do:** + - ✅ Accept flexible option names (e.g., `wisp` or `websocket`) - ✅ Provide sensible defaults - ✅ Document all options clearly @@ -450,6 +470,7 @@ constructor(options) { ## Async/Await Pattern **Do:** + - ✅ Use async/await for asynchronous operations - ✅ Handle promises properly - ✅ Await initialization before marking ready @@ -587,6 +608,7 @@ Essential fields: # Testing Considerations **Test:** + - ✅ HTTP requests (GET, POST, etc.) - ✅ WebSocket connections - ✅ Error handling @@ -599,6 +621,7 @@ Essential fields: # Documentation Standards **Include:** + - ✅ Clear usage examples - ✅ All configuration options documented - ✅ Installation instructions @@ -608,6 +631,7 @@ Essential fields: - ✅ API reference **Format:** + - Use Markdown - Include code examples - Provide both basic and advanced usage @@ -617,6 +641,7 @@ Essential fields: # Security Considerations **Remember:** + - Transports handle sensitive network traffic - Validate all input options - Handle credentials securely @@ -627,6 +652,7 @@ Essential fields: # Performance Best Practices **Do:** + - ✅ Minimize initialization overhead - ✅ Reuse connections when possible - ✅ Handle concurrent requests efficiently @@ -635,6 +661,7 @@ Essential fields: - ✅ Profile performance bottlenecks **Don't:** + - ❌ Block the main thread - ❌ Create excessive connections - ❌ Buffer entire response bodies unnecessarily @@ -643,6 +670,7 @@ Essential fields: # Examples from the Wild ## Traditional Transport (EpoxyTransport) + - ✅ Clean constructor with validation - ✅ Async initialization with WASM loading - ✅ Proper type handling (Blob → ArrayBuffer) @@ -650,6 +678,7 @@ Essential fields: - ✅ Version information exposed ## Traditional Transport (CurlTransport) + - ✅ Flexible option naming (`wisp` or `websocket`) - ✅ Extensive validation with descriptive errors - ✅ Session-based connection management @@ -657,6 +686,7 @@ Essential fields: - ✅ Version logging ## Middleware Transport (Reflux) + - ✅ Dynamic import of base transport - ✅ Composition over inheritance - ✅ Middleware exposure via getter diff --git a/src/content/docs/services/anura.mdx b/src/content/docs/services/anura.mdx index bdc619e..cb96d28 100644 --- a/src/content/docs/services/anura.mdx +++ b/src/content/docs/services/anura.mdx @@ -52,7 +52,7 @@ This does NOT build RootFS. - `rustup` - `wasm-opt` - `make` -- `gcc` (`gcc-multilib` on Debian and Ubuntu x86_64) +- `gcc` (`gcc-multilib` on Debian and Ubuntu x86\_64) - 32 bit version of `glibc` (needed for building rootfs, `lib32-glibc` on Arch Linux) - `clang` - `uuid-runtime` diff --git a/src/content/docs/transports/curl-transport.mdx b/src/content/docs/transports/curl-transport.mdx index e17c8e0..c886607 100644 --- a/src/content/docs/transports/curl-transport.mdx +++ b/src/content/docs/transports/curl-transport.mdx @@ -47,6 +47,7 @@ CurlTransport allows you to route your traffic through intermediate proxies, ena CurlTransport supports three major proxy protocols: ### SOCKS5 (`socks5h://`) + - **Full Name**: Socket Secure version 5 with remote DNS - **Protocol**: Established connection-based proxy protocol - **DNS Resolution**: Remote (DNS queries are resolved by the proxy server) @@ -54,6 +55,7 @@ CurlTransport supports three major proxy protocols: - **Port**: Typically 1080 or 9050 (Tor) ### SOCKS4A (`socks4a://`) + - **Full Name**: Socket Secure version 4A with remote DNS - **Protocol**: Earlier version with remote DNS support - **DNS Resolution**: Remote (DNS queries are resolved by the proxy server) @@ -62,6 +64,7 @@ CurlTransport supports three major proxy protocols: - **Note**: Less feature-rich than SOCKS5 but widely supported ### HTTP (`http://`) + - **Full Name**: HTTP/HTTPS Proxy - **Protocol**: HTTP CONNECT method for tunneling - **DNS Resolution**: Can be local or remote depending on proxy configuration @@ -83,6 +86,7 @@ await connection.setTransport("/path/to/libcurl/index.mjs", [{ ### Examples **SOCKS5 Proxy (Recommended for most use cases):** + ```js await connection.setTransport("/path/to/libcurl/index.mjs", [{ websocket: "wss://example.com/wisp/", @@ -91,6 +95,7 @@ await connection.setTransport("/path/to/libcurl/index.mjs", [{ ``` **HTTP Proxy (Common in corporate environments):** + ```js await connection.setTransport("/path/to/libcurl/index.mjs", [{ websocket: "wss://example.com/wisp/", @@ -99,6 +104,7 @@ await connection.setTransport("/path/to/libcurl/index.mjs", [{ ``` **SOCKS4A Proxy (Legacy systems):** + ```js await connection.setTransport("/path/to/libcurl/index.mjs", [{ websocket: "wss://example.com/wisp/", @@ -111,6 +117,7 @@ await connection.setTransport("/path/to/libcurl/index.mjs", [{ If your proxy requires authentication, include credentials in the URL: **HTTP Proxy with Authentication:** + ```js await connection.setTransport("/path/to/libcurl/index.mjs", [{ websocket: "wss://example.com/wisp/", @@ -119,6 +126,7 @@ await connection.setTransport("/path/to/libcurl/index.mjs", [{ ``` **SOCKS5 Proxy with Authentication:** + ```js await connection.setTransport("/path/to/libcurl/index.mjs", [{ websocket: "wss://example.com/wisp/", @@ -144,6 +152,7 @@ await connection.setTransport("/path/to/libcurl/index.mjs", [{ ``` **With Proxy:** + ```js await connection.setTransport("/path/to/libcurl/index.mjs", [{ websocket: "wss://example.com/wsproxy/", @@ -172,16 +181,19 @@ await connection.setTransport("/path/to/libcurl/index.mjs", [{ ### Example Configurations **High Performance:** + ```js connections: [100, 80, 10] ``` **Conservative (Good for Tor/SOCKS):** + ```js connections: [30, 20, 1] ``` **Default:** + ```js connections: [60, 50, 6] ``` @@ -189,7 +201,9 @@ connections: [60, 50, 6] # Use Cases ## Tor Integration + Route traffic through Tor for anonymity: + ```js await connection.setTransport("/path/to/libcurl/index.mjs", [{ websocket: "wss://example.com/wisp/", @@ -199,13 +213,16 @@ await connection.setTransport("/path/to/libcurl/index.mjs", [{ ``` **Why SOCKS5 with Tor?** + - Remote DNS resolution prevents DNS leaks - Full protocol support for all connection types - Better performance than HTTP proxies - Native Tor compatibility ## Corporate Proxy + Route through a corporate HTTP proxy: + ```js await connection.setTransport("/path/to/libcurl/index.mjs", [{ websocket: "wss://example.com/wisp/", @@ -214,14 +231,17 @@ await connection.setTransport("/path/to/libcurl/index.mjs", [{ ``` **Common Corporate Scenarios:** + - Authenticated proxies with credentials - Multiple proxy servers for load balancing - Proxy auto-configuration (PAC) support via manual URL ## Proxy Chaining + Combine CurlTransport's proxy support with your Wisp server's routing capabilities for multi-hop proxy chains. **Example Multi-Hop Setup:** + 1. Browser → CurlTransport 2. CurlTransport → SOCKS5 Proxy 3. SOCKS5 Proxy → Wisp Server @@ -235,7 +255,9 @@ await connection.setTransport("/path/to/libcurl/index.mjs", [{ ``` ## VPN Exit Nodes + Route traffic through VPN endpoints that expose SOCKS proxies: + ```js await connection.setTransport("/path/to/libcurl/index.mjs", [{ websocket: "wss://example.com/wisp/", @@ -244,7 +266,9 @@ await connection.setTransport("/path/to/libcurl/index.mjs", [{ ``` ## Geographic Routing + Use region-specific proxies for geo-restricted content: + ```js // Route through EU proxy await connection.setTransport("/path/to/libcurl/index.mjs", [{ diff --git a/src/content/docs/transports/reflux.mdx b/src/content/docs/transports/reflux.mdx index a315ec4..f90ea33 100644 --- a/src/content/docs/transports/reflux.mdx +++ b/src/content/docs/transports/reflux.mdx @@ -152,18 +152,21 @@ Plugins consist of JavaScript code with special markers for browser-side and ser ## Available Variables ### Browser-Side Code + - `url` (string): Current page URL - `pluginName` (string): Name of the plugin - All standard browser APIs (document, window, etc.) ### Server-Side Code + - `body` (string): HTML content - `url` (string): Target URL -- `headers` (Record\): Response headers +- `headers` (Record\): Response headers # Use Cases ## Ad Blocking + ```javascript await api.addPlugin({ name: "com.example.adblocker", @@ -179,6 +182,7 @@ await api.addPlugin({ ``` ## Custom UI Injection + ```javascript await api.addPlugin({ name: "com.example.dark-mode", @@ -204,6 +208,7 @@ await api.addPlugin({ ``` ## Request/Response Interception + ```javascript await api.addPlugin({ name: "com.example.analytics", @@ -227,6 +232,7 @@ await api.addPlugin({ ## RefluxAPI Methods ### addPlugin(plugin) + Adds a new plugin to the system. ```typescript @@ -238,6 +244,7 @@ await api.addPlugin({ ``` ### removePlugin(name) + Removes a plugin from the system. ```typescript @@ -245,6 +252,7 @@ await api.removePlugin("com.example.plugin"); ``` ### enablePlugin(name) + Enables a disabled plugin. ```typescript @@ -252,6 +260,7 @@ await api.enablePlugin("com.example.plugin"); ``` ### disablePlugin(name) + Disables an enabled plugin. ```typescript @@ -259,6 +268,7 @@ await api.disablePlugin("com.example.plugin"); ``` ### listPlugins() + Returns a list of all installed plugins. ```typescript @@ -267,6 +277,7 @@ const plugins = await api.listPlugins(); ``` ### getEnabledPlugins() + Returns an array of enabled plugin names. ```typescript @@ -275,6 +286,7 @@ const enabled = await api.getEnabledPlugins(); ``` ### updatePluginSites(name, sites) + Updates the site patterns for a plugin. ```typescript @@ -332,11 +344,13 @@ const middleware = { # Browser Compatibility **Required:** + - ES6+ JavaScript support - IndexedDB/LocalForage - Service Worker support (for BareMux) **Tested:** + - Chrome/Edge 90+ - Firefox 88+ - Safari 14+