scproxy

command module
v0.0.0-...-5aaefcd Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 16, 2026 License: MIT Imports: 16 Imported by: 0

README

scproxy logo


scproxy — A command-line HTTP reverse proxy with intelligent caching

Forked from Madh93/prxy with enhanced features

scproxy stands for Sieve Cache Proxy — filtering and caching HTTP responses efficiently.

Latest release Go Version Go Report Card Build Status License

Features • Installation • Quick Start • Configuration • Caching • License
简体中文


Overview

scproxy(Sieve Cache Proxy) is a lightweight HTTP reverse proxy written in Go that helps you forward HTTP requests through an outbound proxy with intelligent response caching. It's designed for scenarios where you need to:

  • Route multiple services through different local ports
  • Forward traffic via an external HTTP proxy (e.g., corporate proxies, wireproxy, Squid)
  • Cache HTTP responses to reduce bandwidth and improve latency

Features

Core

  • Batch proxy mode — Run multiple routes simultaneously on different ports
  • Outbound proxy chaining — Forward all traffic through an external HTTP proxy
  • Automatic Host header rewriting — Ensures requests reach the correct backend
  • Graceful shutdown — Clean handling of SIGTERM/SIGINT signals

Caching

  • Path-based storage — Cache files mirror URL paths for easy inspection
  • Streaming support — Efficient handling of large files
  • HTTP Range requests — Full support for partial content delivery
  • Configurable policies — Size limits, extension exclusions, auth handling
  • LRU eviction — Automatic cache cleanup when size limit is reached
  • Cache statistics — Track hits, misses, and storage usage

Configuration

  • Multiple sources — CLI flags, config files, and defaults
  • Dynamic routes — Add routes via CLI without editing config
  • Auto-save — CLI settings persist to config file

Installation

curl -L https://github.com/peng-mj/scproxy/releases/latest/download/scproxy_$(uname -s)_$(uname -m).tar.gz | tar -xz -O scproxy > /usr/local/bin/scproxy
chmod +x /usr/local/bin/scproxy

From Source

go install github.com/peng-mj/scproxy@latest

Quick Start

Single Route

Forward one target through an outbound proxy:

scproxy --target https://example.com --proxy http://proxy:8080 --port 8080

Batch Mode (Multiple Routes)

Create a config at ./cache/scproxy.json:

{
  "host": "0.0.0.0",
  "proxy": "http://proxy:8080",
  "routes": [
    {"target": "https://github.com", "port": 8081},
    {"target": "https://gitlab.com", "port": 8082},
    {"target": "https://api.example.com", "port": 8083}
  ],
  "cache": {
    "enabled": true,
    "directory": "./cache"
  }
}

Then run:

scproxy

Add Temporary Route

scproxy --target https://httpbin.org --port 9999

Configuration

Config File

Created automatically at ./config.json on first run. All persistent state (config file, cache data + databases, certificates) lives under one data directory (--data-dir, default: current directory):

<data-dir>/
├── config.json        # configuration
├── cache/             # cached data, cache_index.db, stats.db
└── certs/             # generated TLS certificates
{
  "host": "0.0.0.0",
  "proxy": "",
  "routes": [],
  "cache": {
    "enabled": true,
    "directory": "./cache",
    "excludeLastPfx": ["index.html"]
  },
  "logging": {
    "level": "info",
    "format": "text",
    "output": "stdout"
  }
}

Priority

  1. CLI flags (highest)
  2. Config file
  3. Defaults (lowest)

CLI Options

Flag Description Default
--target, -t Target service URL —
--port, -P Listen port —
--proxy, -x Outbound proxy URL Direct
--host, -H Listen host 0.0.0.0
--config, -c Config file path ./config.json
--data-dir Unified data directory (config.json, cache/, certs/) .
--cache Enable caching true
--clear-cache Clear cache and exit —
--yes Skip confirmation —
--summary, -s Show cache stats —
--version, -v Show version —
--log-level, -l Log level info
--log-output, -o Log output stdout

Caching

Cache Control

Setting Description
enabled Enable/disable caching
directory Storage path (default <data-dir>/cache)
excludeLastPfx URL path suffix patterns to skip

Path Exclusion

excludeLastPfx patterns are matched against the end of the URL path (suffix, case-insensitive):

Pattern Matches
index.html /aa/bb/cc/index.html
.html Any path ending with .html
cc/index.html Any path ending with cc/index.html
/etc/resolv.conf Only this exact path (full-path suffix)
/ubuntu/dists/ Paths ending with /ubuntu/dists/

Rules:

  • All patterns are suffix matches, case-insensitive
  • Directory paths are resolved to their index document before matching: /foo/ is treated as /foo/index.html (per HTTP conventions). Directory patterns like /ubuntu/dists/ are normalized the same way, so they keep matching directory requests
  • As a result, /foo/ and /foo/index.html share the same cache key: caching either one makes the other a cache hit (when not excluded)
  • Deprecated excludeExtensions/excludePaths entries are converted automatically at startup (with a warning) when excludeLastPfx is not set

Example:

{
  "cache": {
    "excludeLastPfx": [
      "/ubuntu/dists/",
      "/etc/resolv.conf",
      "index.html"
    ]
  }
}

Management

View stats:

scproxy --summary

Clear cache:

scproxy --clear-cache          # Interactive
scproxy --clear-cache --yes    # Skip confirmation

Response headers indicate cache status:

  • X-Cache: HIT — Served from cache
  • X-Cache: MISS — Fetched from target
  • X-Cache: BYPASS — Not cached (excluded by policy)

Storage Structure

cache/
├── scproxy.json              # Config file
└── data/
    ├── github.com/
    │   └── releases/
    │       └── file.tar.gz
    └── api.example.com/
        └── endpoint.json

Development

make build          # Build for current platform
make build-all      # Build for all platforms
make test           # Run tests
make lint           # Run linters

License

MIT

Documentation

The Go Gopher

There is no documentation for this package.

Directories

Path Synopsis
internal
cert
Package cert provides self-signed root CA generation and domain certificate signing for the HTTPS reverse proxy.
Package cert provides self-signed root CA generation and domain certificate signing for the HTTPS reverse proxy.
dns
Package dns provides a DNS proxy server that resolves configured domains to a specified IP address (typically the local proxy server), while forwarding all other queries to upstream DNS servers.
Package dns provides a DNS proxy server that resolves configured domains to a specified IP address (typically the local proxy server), while forwarding all other queries to upstream DNS servers.
logging
Package logging manages application logging using the log/slog package.
Package logging manages application logging using the log/slog package.
validation
Package validation provides functionality for validating various types of data, including URLs.
Package validation provides functionality for validating various types of data, including URLs.
version
Package version provides information about the version of the application.
Package version provides information about the version of the application.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL