go-cachecash

Cloning the git repository

This repository uses git-lfs for test data artifacts, among other things; you'll need to install it:

# Ubuntu
apt-get install git-lfs

# macOS
brew install git-lfs

# Archlinux
pacman -S git-lfs

# Windows
Download from https://git-lfs.github.com/

Next, clone the cachecash repo:

git clone [email protected]:cachecashproject/go-cachecash.git "$(go env GOPATH)/src/github.com/cachecashproject/go-cachecash"

And initialize git-lfs in that repo:

cd "$(go env GOPATH)/src/github.com/cachecashproject/go-cachecash"
git lfs install
git lfs fetch
git lfs checkout

Running a local test network

The easiest way to get cachecash up and running is starting the test network with docker-compose. The first step is creating required secrets according to the template files. Then you can build all images:

docker-compose build

Next, bring up the network:

docker-compose up

It's going to take 1-2 minutes until everything is initialized, this includes the postgres initialization, the caches announcing themselves to the bootstrap service, the publisher requesting a list of all caches from the bootstrap service and finally the publisher and the caches negotiating an escrow, and a distributed tracing backend store. After the escrow is setup you can download from the caches using cachecash-curl or typescript-cachecash:

In this case we're going to use the cachecash-curl program at this publisher to see it fetch data. The resulting file (here, output.bin) should exactly match the original artifact (here, testdata/content/file0.bin).

The -logLevel option can be changed to control output verbosity for each program.

make cachecash-curl && ./bin/cachecash-curl -o output.bin -logLevel=debug -trace http://localhost:14268 cachecash://localhost:7070/file0.bin
diff output.bin testdata/content/file0.bin

Setting up a development environment

You will need a working Go toolchain. We tend to stay on the latest stable version.

You will also need some extra code generation tools:

make dev-setup

To generate source from proto files:

make gen

To generate documentation from the proto files:

make gen-docs

Using the base image

To get the base image we use for building our software, type make pull-base-image to receive it. It will be used for all operations around building and running the software in our development environment.

To build the image yourself:

$ make base-image

If you have write access to our repositories on docker hub, you can also push an updated image:

$ make push-base-image

This is recommended whenever your changes land in the master branch, but not before then.

Running tests

# Remove cached results.  (Should not normally be necessary, but can be useful while working on the test suite.)
go clean -testcache

# Run unit and integration tests that do not have external dependencies.
go test -v -race ./...

Running tests that use postgres

To run tests that use postgres, you must launch it first; you can use this command to launch your postgres container:

docker run --name db-hostname -p 5432:5432 -d -e POSTGRES_DB=dbname postgres:11

# Run a test that has external dependencies, including those automatically
# generated by the ORM system.

PSQL_USER=postgres PSQL_SSLMODE=disable PSQL_HOST=localhost PSQL_DBNAME=dbname \
go test -v -race -tags="external_test sqlboiler_test" ./path/to/test/...

Environment variables

CACHECASH_INSECURE can be set for any binary to disable TLS checking against the bootstrap/publisher/observability endpoints. Protocol cryptography is still secure.

Fuzzing

There are fuzzing targets that can be used with go-fuzz.

# install dependencies
go get -u github.com/dvyukov/go-fuzz/go-fuzz github.com/dvyukov/go-fuzz/go-fuzz-build
# start fuzzing
make fuzz