core

README

API

Idempotency

Most of the API endpoints are idempotent. Some endpoints require a client_token parameter that is used for ensuring idempotency. These client tokens are only used as an idempotency key, and cannot be used to lookup entities later.

Documentation

Overview

Package core implements Chain Core and its API.

Index

• Constants
• Variables
• func AuthHandler(handler http.Handler, sdb *sinkdb.DB, ...) http.Handler
• func CheckConfigMaybeExec(ctx context.Context, sdb *sinkdb.DB, nodeAddr string)
• func Config(ctx context.Context, db pg.DB, sdb *sinkdb.DB) (*config.Options, error)
• func RedirectHandler(next http.Handler) http.Handler
• func TLSConfig(certFile, keyFile, rootCAs string) (*tls.Config, error)
• type API
  • func Run(ctx context.Context, confOpts *config.Options, conf *config.Config, db pg.DB, ...) (*API, error)
  • func RunUnconfigured(ctx context.Context, confOpts *config.Options, db pg.DB, sdb *sinkdb.DB, ...) *API
  • func (a *API) ServeHTTP(rw http.ResponseWriter, req *http.Request)
• type RunOption
  • func BlockSigner(signFn func(context.Context, *legacy.Block) ([]byte, error)) RunOption
  • func GeneratorLocal(gen *generator.Generator) RunOption
  • func GeneratorRemote(client *rpc.Client) RunOption
  • func IndexTransactions(b bool) RunOption
  • func MockHSM(hsm *mockhsm.HSM) RunOption
  • func RateLimit(keyFn func(*http.Request) string, burst, perSecond int) RunOption
  • func UseTLS(c *tls.Config) RunOption

Constants

const GrantPrefix = "/core/grant/"

Variables

var ErrNoTLS = errors.New("no TLS configuration available")

var Policies = []string{
	"client-readwrite",
	"client-readonly",
	"crosscore",
	"crosscore-signblock",
	"monitoring",
	"internal",
	"public",
}

Functions

func AuthHandler

func AuthHandler(handler http.Handler, sdb *sinkdb.DB, accessTokens *accesstoken.CredentialStore, tlsConfig *tls.Config, extraGrants []*authz.Grant) http.Handler

func CheckConfigMaybeExec

func CheckConfigMaybeExec(ctx context.Context, sdb *sinkdb.DB, nodeAddr string)

func Config

func Config(ctx context.Context, db pg.DB, sdb *sinkdb.DB) (*config.Options, error)

Config provides access to Chain Core configuration options and their values.

TODO(jackson): Remove the pg.DB argument when the PostgreSQL url is stored in a configuration option.

func RedirectHandler

func RedirectHandler(next http.Handler) http.Handler

RedirectHandler redirects / to /dashboard/.

func TLSConfig

func TLSConfig(certFile, keyFile, rootCAs string) (*tls.Config, error)

TLSConfig returns a TLS config suitable for use as a Chain Core client and server. It reads a PEM-encoded X.509 certificate and private key from certFile and keyFile. If rootCAs is given, it should name a file containing a list of trusted root CA certs, otherwise the returned config uses the system cert pool.

For compatibility, it attempts to read the cert and key from the environment if certFile and keyFile both do not exist in the filesystem.

TLSCRT=[PEM-encoded X.509 certificate]
TLSKEY=[PEM-encoded X.509 private key]

If certFile and keyFile do not exist or are empty and the environment vars are both unset, TLSConfig returns ErrNoTLS.

Types

type API

type API struct {
	// contains filtered or unexported fields
}

API serves the Chain HTTP API

func Run

func Run(
	ctx context.Context,
	confOpts *config.Options,
	conf *config.Config,
	db pg.DB,
	dbURL string,
	sdb *sinkdb.DB,
	c *protocol.Chain,
	store *txdb.Store,
	routableAddress string,
	opts ...RunOption,
) (*API, error)

Run launches a new configured Chain Core. It will start goroutines for the various Core subsystems and enter leader election. It will not start listening for HTTP requests. To begin serving HTTP requests, use API.Handler to retrieve an http.Handler that can be used in a call to http.ListenAndServe.

Either the GeneratorLocal or the GeneratorRemote RunOption is required.

func RunUnconfigured

func RunUnconfigured(ctx context.Context, confOpts *config.Options, db pg.DB, sdb *sinkdb.DB, routableAddress string, opts ...RunOption) *API

RunUnconfigured launches a new unconfigured Chain Core. This is used for Chain Core Developer Edition to expose the configuration UI in the dashboard. API authentication still applies to an unconfigured Chain Core.

func (*API) ServeHTTP

func (a *API) ServeHTTP(rw http.ResponseWriter, req *http.Request)

type RunOption

type RunOption func(*API)

RunOption describes a runtime configuration option.

func BlockSigner

func BlockSigner(signFn func(context.Context, *legacy.Block) ([]byte, error)) RunOption

BlockSigner configures the Core to use signFn to handle block-signing requests. In production, this will be a function to call out to signerd and its HSM. In development, it'll use the MockHSM.

func GeneratorLocal

func GeneratorLocal(gen *generator.Generator) RunOption

GeneratorLocal configures the launched Core to run as a Generator.

func GeneratorRemote

func GeneratorRemote(client *rpc.Client) RunOption

GeneratorRemote configures the launched Core to fetch blocks from the provided remote generator.

func IndexTransactions

func IndexTransactions(b bool) RunOption

IndexTransactions configures whether or not transactions should be annotated and indexed for the query engine.

func MockHSM

func MockHSM(hsm *mockhsm.HSM) RunOption

MockHSM configures the Core to expose the MockHSM endpoints. It is only included in non-production builds.

func RateLimit

func RateLimit(keyFn func(*http.Request) string, burst, perSecond int) RunOption

RateLimit adds a rate-limiting restriction, using keyFn to extract the key to rate limit on. It will allow up to burst requests in the bucket and will refill the bucket at perSecond tokens per second.

func UseTLS

func UseTLS(c *tls.Config) RunOption

UseTLS configures the Core to use TLS with the given config when communicating between Core processes. If c is nil, TLS is disabled.