Naughty Platypus Memorabilia

    straightforward

    2.0.3 • Public • Published

    🏴 straightforward Build Status

    A straightforward forward-proxy written in Node.js

    Goals

    • Extremely focused (~200 SLOC), no-fuzz forward proxy
    • Support HTTP, HTTPS, CONNECT & Websockets (wss)
    • Performant: By default all requests/responses are streamed
    • No external dependencies, small, self-contained, tested
    • Support both cli and extensible programmatic usage
    • Straightforward: no implicit magic or abstractions

    What you can do with it

    • Start an explicit forwarding proxy in seconds that just works
    • Optionally use authentication and a white-/blacklist for hosts
    • Block requests, fake or modify responses
    • Allow others to surf with your IP address
    • Use it programmatically to do whatever you want

    What this is not

    Installation

    # Use directly with no installation (npx is part of npm): 
    ❯❯❯ npx straightforward --port 9191
     
    # Or install globally: 
    ❯❯❯ npm install -g straightforward

    Usage (cli)

    ❯❯❯ straightforward --help
     
    Usage: straightforward --port 9191 [options]
     
    Options:
      --version         Show version number                                [boolean]
      --port, -p        Port to bind on                     [number] [default: 9191]
      --auth, -a        Enable proxy authentication                         [string]
      --blacklist-host  Allow all requests except to blacklist              [string]
      --whitelist-host  Deny all requests except to whitelist               [string]
      --block-msg       Show custom block message (http only)               [string]
      --replace-text    Replace text on websites (http only)                [string]
      --debug, -d       Enabled debug output                               [boolean]
      --cluster, -c     Run a cluster of proxies (using number of CPUs)    [boolean]
      --cluster-count   Specify how many cluster workers to spawn           [number]
      --quiet, -q       Suppress request logs                              [boolean]
      --silent, -s      Dont print anything to stdout                     [boolean]
      -h, --help        Show help                                          [boolean]
     
    Examples:
      straightforward --auth "user:pass"               Require authentication
      straightforward --whitelist-host "a.com,b.net"   Allow specific hosts
      straightforward --blacklist-host "a.com,b.net"   Block specific hosts
      straightforward --block-msg "<h1>Nope ಠ_ಠ</h1>"  Custom block message
      straightforward --replace-text "cloud:butt"      Replace all occurences of cloud with butt
     
    Use with cURL:
      curl --proxy https://localhost:9191 'http://example.com' -v

    Usage (code)

    const Straightforward = require('straightforward')
     
    ;(async () => {
      // Start proxy server
      const sf = await new Straightforward().listen(9191)
      console.log(`Proxy listening on http://localhost:9191`)
     
      // Log http requests
      sf.onRequest(async ({ req, res }, next) => {
        console.log(`http request: ${req.url}`)
        // Note the common middleware pattern, use `next()`
        // to pass the request to the next handler.
        return next()
      })
     
      // Log connect (https) requests
      sf.onConnect(async ({ req, res }, next) => {
        console.log(`connect request: ${req.url}`)
        return next()
      })
     
      // Filter some requests dynamically
      const blockRequest = sf.middleware.blockRequest({
        filterFn: (host, url) => host.includes('malware.com'),
        responseMsg: `<h1>None shall pass. 🐗</h1>`
      })
      sf.onRequest(blockRequest) // for http
      sf.onConnect(blockRequest) // for https
     
      // Replace text on http://example.com for fun and glory
      sf.onResponse(sf.middleware.replaceText({
        filterFn: (host, url) => host.includes('example.com'),
        replacerFn: (str) => str.replace(/example/ig, 'FOOBAR')
      }))
    })()

    foobar

    API

    onRequest

    onResponse

    onConnect

    License

    MIT

    Install

    npm i straightforward

    DownloadsWeekly Downloads

    11

    Version

    2.0.3

    License

    MIT

    Unpacked Size

    161 kB

    Total Files

    18

    Last publish

    Collaborators

    • berstend