j8a

package module
v0.7.4 Latest Latest
Warning

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

Go to latest
Published: Feb 13, 2021 License: Apache-2.0 Imports: 43 Imported by: 1

README

Circleci Builds Github Workflows Dependabot Github Issues Github Activity
Codeclimate Maintainability Codeclimate Test Coverage SSLLabs Rating Go Version License Docker Pulls Version

What is j8a?

j8a [ dʒʌbbʌ ] is a modern TLS 1.3 reverse proxy server designed to front your micro-service JSON APIs. It was created to better meet the needs of devops engineers who need fine-grained visibility of, and better control over HTTP traffic without sacrificing performance.

Features

  • Fast! 20k req/s HTTPS traffic on single CPU core.
  • Secure. TLS1.2, TLS/1.3 termination with zero config A+ SSLLabs rating. No weak ciphers ever again.
  • Observable. API request tracing w/ correlation ID for upstream micro-services.
  • APM. CPU, memory logging built-in. Daily TLS health and validity check for your full certificate chain.
  • JWT token validation with full JWK(S) support for RFC 7519.
  • HTTP/1.1 and HTTP/2 support w/ upstream <> downstream protocol translation.
  • Docker native

Up and running

Docker

docker pull simonmittag/j8a &&
docker run -e J8ACFG_YML -p443:443 simonmittag/j8a

Linux / Darwin

go install github.com/simonmittag/j8a/cmd/j8a && j8a

Configuration

Environment Variables

J8ACFG_YML

Supply the server configuration to the running process in .yml format

J8ACFG_YML="---
            connection:
              downstream:
                readTimeoutSeconds: 3
                roundTripTimeoutSeconds: 20
                idleTimeoutSeconds: 30
                port: 80
                mode: HTTP
                maxBodyBytes: 65535
              upstream:
                socketTimeoutSeconds: 3
                readTimeoutSeconds: 30
                idleTimeoutSeconds: 10
                maxAttempts: 4
                poolSize: 8
                tlsInsecureSkipVerify: true
            routes:
              - path: "/todos"
                resource: jsonplaceholder
            resources:
              jsonplaceholder:
                - url:
                    scheme: https
                    host: jsonplaceholder.typicode.com
                    port: 443"
LOGLEVEL

Loglevel for stdout, one of TRACE, DEBUG, INFO or WARN

LOGLEVEL="DEBUG"
TZ

TimeZone

TZ="Australia/Sydney"

Contributions

The j8a team welcomes all contributors. Everyone interacting with the project's codebase, issue trackers, chat rooms and mailing lists is expected to follow the code of conduct

Documentation

Index

Constants

View Source
const DefaultConfigFile = "j8acfg.yml"
View Source
const HTTP = "HTTP"
View Source
const J8ACFG_YML = "J8ACFG_YML"
View Source
const TLS = "TLS"
View Source
const XRequestID = "X-Request-Id"

XRequestID is a per HTTP request unique identifier

Variables

View Source
var ConfigFile = ""
View Source
var ID string = "unknown"

ID is a unique server ID

View Source
var TZ = "UTC"
View Source
var Version string = "v0.7.4"

Version is the server version

Functions

func BootStrap

func BootStrap()

BootStrap starts up the server from a ServerConfig

func Gunzip

func Gunzip(input []byte) *[]byte

Gunzip a []byte

func Gzip

func Gzip(input []byte) *[]byte

Gzip a []byte

Types

type AboutResponse

type AboutResponse struct {
	J8a      string
	ServerID string
	Version  string
}

AboutResponse exposes standard environment

func (AboutResponse) AsJSON

func (aboutResponse AboutResponse) AsJSON() []byte

AsJSON renders the status Code response into a JSON string as []byte

func (AboutResponse) AsString

func (aboutResponse AboutResponse) AsString() string

type Atmpt

type Atmpt struct {
	URL        *URL
	Label      string
	Count      int
	StatusCode int

	CompleteHeader chan struct{}
	CompleteBody   chan struct{}
	Aborted        <-chan struct{}
	AbortedFlag    bool
	CancelFunc     func()
	// contains filtered or unexported fields
}

Atmpt wraps connection attempts to specific upstreams that are already mapped by label

type Config

type Config struct {
	Policies   map[string]Policy
	Routes     Routes
	Jwt        map[string]*Jwt
	Resources  map[string][]ResourceMapping
	Connection Connection
}

Config is the system wide configuration for j8a

type Connection

type Connection struct {
	Downstream Downstream
	Upstream   Upstream
}

Connection Params

type Down

type Down struct {
	Req         *http.Request
	Resp        Resp
	Method      string
	Path        string
	URI         string
	UserAgent   string
	Body        []byte
	Aborted     <-chan struct{}
	AbortedFlag bool
	ReqTooLarge bool

	HttpVer string
	TlsVer  string
	// contains filtered or unexported fields
}

Down wraps downstream exchange

type Downstream

type Downstream struct {
	// ReadTimeoutSeconds is the maximum duration for reading the entire
	// request, including the body, the downstream user agent sends to us.
	ReadTimeoutSeconds int

	// WriteTimeoutSeconds is the maximum duration round trip time in seconds any
	// single request spends in the server, this includes the time to read the request,
	// processing upstream attempts and writing the response into downstream socket.
	RoundTripTimeoutSeconds int

	// IdleTimeoutSeconds is the maximum duration, a downstream idle socket connection is kept open
	// before the server hangs up on the downstream user agent.
	IdleTimeoutSeconds int

	// MaxBodyBytes is the maximum size of the incoming HTTP request body before it is rejected
	MaxBodyBytes int64

	// Serving Mode, can be "TLS"
	Mode string

	// Serving on this port
	Port int

	// TLS x509 certificate
	Cert string

	// TLS secret key
	Key string
}

Downstream params for the HTTP or TLS server that j8a exposes

type HTTPClient

type HTTPClient interface {
	Do(req *http.Request) (*http.Response, error)
	Get(uri string) (*http.Response, error)
}

type Jwt added in v0.7.0

type Jwt struct {
	Name string
	Alg  string
	// Jwt key supports pem encoding for public keys, certificates unencoded secrets for hmac.
	Key string
	// JwksUrl loads remotely.
	JwksUrl               string
	RSAPublic             KeySet
	ECDSAPublic           KeySet
	Secret                KeySet
	AcceptableSkewSeconds string
	Claims                []string
	// contains filtered or unexported fields
}

func NewJwt added in v0.7.1

func NewJwt(name string, alg string, key string, jwksUrl string, acceptableSkewSeconds string, claims ...string) *Jwt

func (*Jwt) Init added in v0.7.1

func (jwt *Jwt) Init()

we need this separate because the JSON unmarshaller creates this object without asking us.

func (*Jwt) LoadJwks added in v0.7.0

func (jwt *Jwt) LoadJwks() error

TODO this method needs a refactor and has high cognitive complexity

func (*Jwt) Validate added in v0.7.1

func (jwt *Jwt) Validate() error

type KeySet added in v0.7.0

type KeySet []KidPair

func (*KeySet) Find added in v0.7.1

func (ks *KeySet) Find(kid string) interface{}

func (*KeySet) Upsert added in v0.7.1

func (ks *KeySet) Upsert(kp KidPair)

type KidPair added in v0.7.0

type KidPair struct {
	Kid string
	Key interface{}
}

type LabelWeight

type LabelWeight struct {
	Label  string
	Weight float64
}

LabelWeight describes routing to labels

type PDuration

type PDuration time.Duration

func (PDuration) AsDays

func (p PDuration) AsDays() int

func (PDuration) AsDuration

func (p PDuration) AsDuration() time.Duration

func (PDuration) AsString

func (p PDuration) AsString() string

type Policy

type Policy []LabelWeight

Policy defines an array of LabelWeights used for routing

func (Policy) Len

func (policy Policy) Len() int

func (Policy) Less

func (policy Policy) Less(i, j int) bool

func (Policy) Swap

func (policy Policy) Swap(i, j int)

type Proxy

type Proxy struct {
	XRequestID    string
	XRequestDebug bool
	Up            Up
	Dwn           Down
	Route         *Route
}

Proxy wraps data for a single downstream request/response with multiple upstream HTTP request/response cycles.

type ResourceMapping

type ResourceMapping struct {
	Name   string
	Labels []string
	URL    URL
}

ResourceMapping describes upstream servers

type Resp

type Resp struct {
	Writer        http.ResponseWriter
	StatusCode    int
	Message       string
	SendGzip      bool
	Body          *[]byte
	ContentLength int64
}

Resp wraps downstream http response writer and data

type Route

type Route struct {
	Path      string
	PathRegex *regexp.Regexp
	Transform string
	Resource  string
	Policy    string
	Jwt       string
}

Route maps a Path to an upstream resource

type Routes

type Routes []Route

func (Routes) Len

func (s Routes) Len() int

func (Routes) Less

func (s Routes) Less(i, j int) bool

func (Routes) Swap

func (s Routes) Swap(i, j int)

type Runtime

type Runtime struct {
	Config
	Start  time.Time
	Memory []sample
}

Runtime struct defines runtime environment wrapper for a config.

var Runner *Runtime

Runner is the Live environment of the server

type StatusCodeResponse

type StatusCodeResponse struct {
	AboutResponse
	Code    int
	Message string
}

StatusCodeResponse defines a JSON structure for a canned HTTP response

func (StatusCodeResponse) AsJSON

func (statusCodeResponse StatusCodeResponse) AsJSON() []byte

AsJSON renders the status Code response into a JSON string as []byte

func (StatusCodeResponse) AsString

func (statusCodeResponse StatusCodeResponse) AsString() string

type TLSType

type TLSType string
const (
	TLS12         TLSType = "TLS1.2"
	TLS13         TLSType = "TLS1.3"
	TLS_UNKNOWN   TLSType = "unknown"
	TLS_NONE      TLSType = "none"
	Authorization         = "Authorization"
	Sep                   = " "
)
type TlsLink struct {
	// contains filtered or unexported fields
}

type URL

type URL struct {
	Scheme string
	Host   string
	Port   uint16
}

URL describes host mapping

func (URL) String

func (u URL) String() string

String representation of our URL struct

type Up

type Up struct {
	Atmpt  *Atmpt
	Atmpts []Atmpt
	Count  int
}

Up wraps upstream

type Upstream

type Upstream struct {

	// PoolSize is the maximum size of the client socket connection pool for idle connections
	PoolSize int

	// IdleTimeoutSeconds is the total wait period in seconds before we hang up on an idle upstream connection.
	IdleTimeoutSeconds int

	// SocketTimeoutSeconds is the wait period to establish socket connection with an upstream server.
	// This setting controls roundtrip time for simple TCP connections, combined with handshake time for TLS
	// if applicable.
	SocketTimeoutSeconds int

	// ReadTimeoutSeconds is the wait period to read the entire upstream response once connection was established
	// before an individual upstream request is aborted
	ReadTimeoutSeconds int

	// MaxAttempts is the maximum allowable number of request attempts to obtain a successful response for repeatable
	// HTTP requests.
	MaxAttempts int

	// TlsInsecureSkipVerify skips the host name validation and certificate chain verification of upstream connections
	// using TLS. Use this only for testing or if you know what you are doing. Defaults to false
	TlsInsecureSkipVerify bool
}

Upstream connection params for remote servers that are being proxied

Directories

Path Synopsis
cmd
j8a command

Jump to

Keyboard shortcuts

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