proxy-lite/README.md

infinite-noodle

infinite-noodle is a small Go service that combines:

• a web UI for viewing configured TCP proxies
• a login-protected UI with user and admin account management
• a Bitcask-backed data store for persisted proxy definitions
• a TCP proxy runner built with Go's standard net package

This README is written for working in a GitHub Codespace.

What It Does

Each "noodle" is a TCP forwarding rule with:

• a name
• an allowed source list (All, one or more IPs, or CIDR ranges)
• a listen port
• a destination host
• a destination port
• an expiration duration
• an up/down state
• the user who created it

When the app starts, it loads saved noodles from the local database and starts any active proxy routes. It also serves a web UI for creating, pausing, resuming, and deleting them.

Current State

The project is functional enough to:

• start the web app
• create a default admin user on a new database
• require login before the proxy management UI is available
• support two user levels: regular and admin
• let any signed-in user change their own password
• let admin users create users, change roles, change any user's password, and delete user accounts
• load stored proxy definitions from ./infinite.db
• create new noodles from the UI
• run active TCP and UDP proxies
• restrict a proxy to comma-separated source IPs and CIDR ranges
• update expiration values in the database every second while a proxy is active
• close and delete expired noodles automatically
• pause a noodle from the UI without decrementing its expiration
• delete existing noodles from the UI with confirmation

Current limitations:

• there is no REST API; management is currently through the server-rendered UI
• protocols are limited to TCP and UDP

Running In A Codespace

This repo expects a Go toolchain to be available in the Codespace. If it is missing, install or add Go first.

Start the app:

go run ./cmd/infinite-noodle

Default runtime settings:

• host: 0.0.0.0
• web UI port: 7878
• database path: ./infinite.db

Open the app in the browser from the forwarded port for 7878.

On a brand-new database, the app creates a default UI user:

• username: admin
• password: admin
• role: admin

Any signed-in user can access /users to manage their own password. Admin users also get full user management on that page.

You can also override the defaults:

go run ./cmd/infinite-noodle -host 0.0.0.0 -port 7878 -data ./infinite.db

Available flags:

• -host: host/interface to bind the web server to
• -port: web server port
• -data: path to the Bitcask database directory
• -test: seeds the database with sample noodles on startup

UI Behavior

The web UI is protected by a login page. After signing in, the main table includes an add row for creating a proxy with:

• Name
• Allow From: accepts All, comma-separated IP addresses, or CIDR ranges such as 10.0.0.5, 192.168.1.0/24
• Proto: choose TCP or UDP
• Listen Port
• Destination Port
• Destination Host
• Expiration: parsed as a Go time.Duration such as 30s, 5m, or 1h15m

The Status column is a checkbox:

• checked: the proxy is active and the expiration counts down
• unchecked: the proxy is closed and the expiration is paused

The table also shows:

• Created By: the authenticated user who created the proxy

Delete actions in the UI prompt for confirmation before the request is submitted.

The /users page behavior depends on role:

• regular: can change their own password
• admin: can create users, change roles, change any password, and delete users

The expiration value is shown as a live countdown in the browser. When it reaches zero, the row is removed from the UI and the noodle is deleted from the database.

Codespaces Port Notes

In Codespaces, you will usually need to forward:

• 7878 for the web UI
• any listen ports used by active noodles

Example:

• if a noodle listens on 5555, forward port 5555
• if it proxies to another service running inside the Codespace on 6666, that destination only needs forwarding if you also want direct browser or external access to it

Quick Local Proxy Demo

The repo includes simple Python test scripts in test/server.py and test/client.py.

Typical flow:

1. Run the app with go run ./cmd/infinite-noodle
2. Start the test echo server on 127.0.0.1:6666
3. Add a noodle in the UI that listens on 5555 and forwards to 127.0.0.1:6666
4. Run the test client, which connects to 127.0.0.1:5555

Building Binaries

The repo includes build.sh, which builds binaries for:

• Linux amd64
• macOS arm64
• macOS amd64
• Windows arm64
• Windows amd64

Run:

sh build.sh

Artifacts are written under ./target/.

To build only the Linux amd64 target:

GOOS=linux GOARCH=amd64 go build -buildvcs=false -o target/infinite-noodle.net-proxy ./cmd/infinite-noodle

Important Files

• cmd/infinite-noodle/main.go: binary entrypoint and CLI flags
• internal/app/app.go: app startup, HTTP server, and proxy lifecycle
• internal/noodle/database.go: Bitcask storage layer
• internal/web/auth.go: login, sessions, and role-based access control
• internal/web/handlers.go: HTML handlers
• internal/assets/templates/index.html: UI template
• internal/assets/templates/login.html: login page
• internal/assets/templates/users.html: user configuration page

Verification Note

The reorganized project layout was verified with go test ./... and go build ./... in this workspace.