username/derp
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: make SOCKS5 proxy configurable per adapter

Browse Source 
Add `proxy` config option to server (IRC), teams, telegram, and mumble
sections. IRC defaults to false (preserving current direct-connect
behavior); all others default to true. The `derp.http` module now
accepts `proxy=True/False` on urlopen, create_connection,
open_connection, and build_opener -- when false, uses stdlib directly.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
user
2026-02-21 21:19:22 +01:00
parent ca46042c41
commit 9d4cb09069
17 changed files with 355 additions and 47 deletions
Download Patch File Download Diff File Expand all files Collapse all files

11
docs/API.md
View File

@@ -189,14 +189,15 @@ SQLite-backed key-value store. Each plugin gets its own namespace.
## `derp.http` -- HTTP & Network
All outbound traffic routes through the configured SOCKS5 proxy.
HTTP/TCP helpers with optional SOCKS5 proxy routing. All functions accept
a `proxy` parameter (default `True`) to toggle SOCKS5.
| Function | Signature | Description |
|----------|-----------|-------------|
| `urlopen` | `(req, *, timeout=None, context=None, retries=None)` | Proxy-aware HTTP request with connection pooling and retries |
| `build_opener` | `(*handlers, context=None)` | Proxy-aware `urllib.request.build_opener` replacement |
| `create_connection` | `(address, *, timeout=None)` | SOCKS5-proxied `socket.create_connection` with retries |
| `open_connection` | `(host, port, *, timeout=None)` | SOCKS5-proxied `asyncio.open_connection` with retries |
| `urlopen` | `(req, *, timeout=None, context=None, retries=None, proxy=True)` | HTTP request with optional SOCKS5, connection pooling, retries |
| `build_opener` | `(*handlers, context=None, proxy=True)` | Build URL opener, optionally with SOCKS5 handler |
| `create_connection` | `(address, *, timeout=None, proxy=True)` | TCP `socket.create_connection` with optional SOCKS5, retries |
| `open_connection` | `(host, port, *, timeout=None, proxy=True)` | Async `asyncio.open_connection` with optional SOCKS5, retries |
---

9
docs/CHEATSHEET.md
View File

@@ -488,6 +488,7 @@ Auth: HMAC-SHA256 via `X-Signature` header. Starts on IRC connect.
# config/derp.toml
[teams]
enabled = true
proxy = true # SOCKS5 proxy for outbound HTTP
bot_name = "derp"
bind = "127.0.0.1"
port = 8081
@@ -510,6 +511,7 @@ Replies returned as JSON in HTTP response. IRC-only commands (kick, ban, topic)
# config/derp.toml
[telegram]
enabled = true
proxy = true # SOCKS5 proxy for HTTP
bot_token = "123456:ABC-DEF..." # from @BotFather
poll_timeout = 30 # long-poll seconds
admins = [123456789] # Telegram user IDs
@@ -517,8 +519,8 @@ operators = []
trusted = []
```
Long-polling via `getUpdates` -- no public endpoint needed. All HTTP
through SOCKS5 proxy. Strips `@botusername` suffix in groups. Messages
Long-polling via `getUpdates` -- no public endpoint needed. HTTP through
SOCKS5 proxy by default (`proxy = true`). Strips `@botusername` suffix in groups. Messages
split at 4096 chars. IRC-only commands are no-ops. ~90% of plugins work.
## Mumble Integration
@@ -527,6 +529,7 @@ split at 4096 chars. IRC-only commands are no-ops. ~90% of plugins work.
# config/derp.toml
[mumble]
enabled = true
proxy = true # SOCKS5 proxy for TCP
host = "mumble.example.com"
port = 64738
username = "derp"
@@ -537,7 +540,7 @@ operators = []
trusted = []
```
TCP/TLS via SOCKS5 proxy. Text chat only (no voice). Minimal protobuf
TCP/TLS via SOCKS5 proxy by default (`proxy = true`). Text chat only (no voice). Minimal protobuf
codec (no external dep). HTML stripped on receive, escaped on send.
IRC-only commands are no-ops. ~90% of plugins work.

22
docs/USAGE.md
View File

@@ -32,6 +32,7 @@ All settings in `config/derp.toml`.
host = "irc.libera.chat" # IRC server hostname
port = 6697 # Port (6697 = TLS, 6667 = plain)
tls = true # Enable TLS encryption
proxy = false # Route through SOCKS5 proxy (default: false)
nick = "derp" # Bot nickname
user = "derp" # Username (ident)
realname = "derp IRC bot" # Real name field
@@ -1323,6 +1324,7 @@ required -- raw asyncio HTTP, same pattern as the webhook plugin.
```toml
[teams]
enabled = true
proxy = true # Route outbound HTTP through SOCKS5
bot_name = "derp" # outgoing webhook display name
bind = "127.0.0.1" # HTTP listen address
port = 8081 # HTTP listen port
@@ -1418,6 +1420,7 @@ the shared plugin registry. Replies are sent immediately via `sendMessage`.
```toml
[telegram]
enabled = true
proxy = true # Route HTTP through SOCKS5
bot_token = "123456:ABC-DEF..." # from @BotFather
poll_timeout = 30 # long-poll timeout in seconds
admins = [123456789] # Telegram user IDs (numeric)
@@ -1472,19 +1475,20 @@ this automatically: `!help@mybot` becomes `!help`.
### Transport
All HTTP traffic (API calls, long-polling) routes through the SOCKS5
proxy at `127.0.0.1:1080` via `derp.http.urlopen`. No direct outbound
connections are made.
proxy at `127.0.0.1:1080` via `derp.http.urlopen` when `proxy = true`
(default). Set `proxy = false` to connect directly.
## Mumble Integration
Connect derp to a Mumble server via TCP/TLS protobuf control channel.
Text chat only (no voice). All TCP is routed through the SOCKS5 proxy.
No protobuf library dependency -- uses a minimal built-in varint/field
encoder/decoder for the ~7 message types needed.
Text chat only (no voice). TCP is routed through the SOCKS5 proxy when
`proxy = true` (default). No protobuf library dependency -- uses a
minimal built-in varint/field encoder/decoder for the ~7 message types
needed.
### How It Works
The bot connects to the Mumble server over TLS (via SOCKS5), sends
The bot connects to the Mumble server over TLS, sends
Version and Authenticate messages, then enters a read loop. It tracks
channels (ChannelState), users (UserState), and dispatches commands
from TextMessage messages through the shared plugin registry.
@@ -1494,6 +1498,7 @@ from TextMessage messages through the shared plugin registry.
```toml
[mumble]
enabled = true
proxy = true # Route TCP through SOCKS5
host = "mumble.example.com" # Mumble server hostname
port = 64738 # Default Mumble port
username = "derp" # Bot username
@@ -1550,7 +1555,8 @@ unescapes entities. On send, text is HTML-escaped. Action messages use
### Transport
All TCP connections route through the SOCKS5 proxy at `127.0.0.1:1080`
via `derp.http.create_connection`. TLS is applied on top of the proxied
TCP connections route through the SOCKS5 proxy at `127.0.0.1:1080`
via `derp.http.create_connection` when `proxy = true` (default). Set
`proxy = false` to connect directly. TLS is applied on top of the
socket. Mumble commonly uses self-signed certificates, so `tls_verify`
defaults to `false`.