npm-cache-proxy

npm-cache-proxy is a lightweight npm caching proxy written in Go that achives warp speeds by using Redis for data storage. B-b-blazing fast!

Table of Contents

Getting started
CLI
Programmatic usage
- Example
Deployment
Benchmark
License

Getting started

Release binaries for different platforms can be downloaded on the Releases page. Also, Docker image is provided.

The fastest way to get started with NCP is to use Docker image:

# run proxy inside of docker container in background
docker run -e REDIS_ADDRESS=host.docker.internal:6379 -p 8080:8080 -it emeralt/npm-cache-proxy -d

# configure npm to use caching proxy as registry
npm config set registry http://localhost:8080

CLI

Additionally, NCP provides a command line utility for proxy configuration and data management.

Global Options	Env	Default	Description
`--redis-address <address>`	`REDIS_ADDRESS`	`http://localhost:6379`	Redis address
`--redis-database <database>`	`REDIS_DATABASE`	`0`	Redis database
`--redis-password <password>`	`REDIS_PASSWORD`	-	Redis password
`--redis-prefix <prefix>`	`REDIS_PREFIX`	`ncp-`	Redis keys prefix

`ncp`

Start proxy server.

ncp --listen "localhost:1234" # listen on port 1234

Options	Env	Default	Description
`--listen <address>`	`LISTEN_ADDRESS`	`locahost:8080`	Address to listen
`--upstream <address>`	`UPSTREAM_ADDRESS`	`https://registry.npmjs.org`	Upstream registry address
`--cache-limit <count>`	`CACHE_LIMIT`	-	Cached packages count limit
`--cache-ttl <timeout>`	`CACHE_TTL`	`3600`	Cache expiration timeout in seconds

`ncp list`

List all cached packages.

`ncp purge`

Purge all cached packages.

Programmatic usage

Along with the CLI, go package is provided. Documentation is available on godoc.org.

go get -u github.com/emeralt/npm-cache-proxy/proxy

Example

package main

import (
	"net/http"
	"time"

	npmproxy "github.com/emeralt/npm-cache-proxy/proxy"
	redis "github.com/go-redis/redis"
)

func main() {
	proxy := npmproxy.Proxy{
		// you can provide you own Database
		// or use an existing one
		Database: npmproxy.DatabaseRedis{
			Client: redis.NewClient(&redis.Options{
				Addr:     "localhost:6379",
			}),
		},

		// allows to reuse tcp connections
		HttpClient: &http.Client{},

		// allows to get options dynamically
		GetOptions: func() (npmproxy.Options, error) {
			return npmproxy.Options{
				DatabasePrefix:     "ncp-",
				DatabaseExpiration: 1 * time.Hour,
				UpstreamAddress:    "https://registry.npmjs.org",
			}, nil
		},
	}

	// listen on http://localhost:8080
	proxy.Server(npmproxy.ServerOptions{
		ListenAddress: "localhost:8080",
	}).ListenAndServe()
}

Deployment

NCP can be deployed using Kubernetes, Docker Compose or any other container orchestration platform. NCP supports running indefinite amount of instances simultaneously.

Benchmark

Macbook Pro 15″ 2017, Intel Core i7-7700HQ. Note GOMACPROCS=1.

# GOMAXPROCS=1 ncp --listen localhost:8080

$ go-wrk -c 100 -d 5 http://localhost:8080/ascii
Running 5s test @ http://localhost:8080/ascii
  100 goroutine(s) running concurrently
33321 requests in 5.00537759s, 212.69MB read
Requests/sec:		6657.04
Transfer/sec:		42.49MB
Avg Req Time:		15.02169ms
Fastest Request:	230.514µs
Slowest Request:	571.420487ms
Number of Errors:	0

License

MIT

5.0 KiB Raw Blame History