runtime

Documentation

Overview

Package runtime contains the entry point to the policy engine.

Index

• func NewLoggingHandler(logger logging.Logger, inner http.Handler) http.Handler
• func RegisterPlugin(name string, factory plugins.Factory)
• type LoggingConfig
• type LoggingHandler
  • func (h *LoggingHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type Params
  • func NewParams() Params
• type Runtime
  • func NewRuntime(ctx context.Context, params Params) (*Runtime, error)
  • func (rt *Runtime) Addrs() []string
  • func (rt *Runtime) DiagnosticAddrs() []string
  • func (rt *Runtime) Serve(ctx context.Context) error
  • func (rt *Runtime) SetDistributedTracingLogging()
  • func (rt *Runtime) StartREPL(ctx context.Context)
  • func (rt *Runtime) StartServer(ctx context.Context)

Functions

func NewLoggingHandler

func NewLoggingHandler(logger logging.Logger, inner http.Handler) http.Handler

NewLoggingHandler returns a new http.Handler.

func RegisterPlugin

func RegisterPlugin(name string, factory plugins.Factory)

RegisterPlugin registers a plugin factory with the runtime package. When the runtime is created, the factories are used to parse plugin configuration and instantiate plugins. If no configuration is provided, plugins are not instantiated. This function is idempotent.

Types

type LoggingConfig

type LoggingConfig struct {
	Level           string
	Format          string
	TimestampFormat string
}

LoggingConfig stores the configuration for OPA's logging behaviour.

type LoggingHandler

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

LoggingHandler returns an http.Handler that will print log messages containing the request information as well as response status and latency.

func (*LoggingHandler) ServeHTTP

func (h *LoggingHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

type Params

type Params struct {
	// Globally unique identifier for this OPA instance. If an ID is not specified,
	// the runtime will generate one.
	ID string

	// Addrs are the listening addresses that the OPA server will bind to.
	Addrs *[]string

	// DiagnosticAddrs are the listening addresses that the OPA server will bind to
	// for read-only diagnostic API's (/health, /metrics, etc)
	DiagnosticAddrs *[]string

	// H2CEnabled flag controls whether OPA will allow H2C (HTTP/2 cleartext) on
	// HTTP listeners.
	H2CEnabled bool

	// Authentication is the type of authentication scheme to use.
	Authentication server.AuthenticationScheme

	// Authorization is the type of authorization scheme to use.
	Authorization server.AuthorizationScheme

	// Certificate is the certificate to use in server-mode. If the certificate
	// is nil, the server will NOT use TLS.
	Certificate *tls.Certificate

	// CertificateFile and CertificateKeyFile are the paths to the cert and its
	// keyfile. It'll be used to periodically reload the files from disk if they
	// have changed. The server will attempt to refresh every 5 minutes, unless
	// a different CertificateRefresh time.Duration is provided
	CertificateFile    string
	CertificateKeyFile string
	CertificateRefresh time.Duration

	// CertPool holds the CA certs trusted by the OPA server.
	CertPool *x509.CertPool
	// CertPoolFile, if set permits the reloading of the CA cert pool from disk
	CertPoolFile string

	// MinVersion contains the minimum TLS version that is acceptable.
	// If zero, TLS 1.2 is currently taken as the minimum.
	MinTLSVersion uint16

	// HistoryPath is the filename to store the interactive shell user
	// input history.
	HistoryPath string

	// Output format controls how the REPL will print query results.
	// Default: "pretty".
	OutputFormat string

	// Paths contains filenames of base documents and policy modules to load on
	// startup. Data files may be prefixed with "<dotted-path>:" to indicate
	// where the contained document should be loaded.
	Paths []string

	// Optional filter that will be passed to the file loader.
	Filter loader.Filter

	// BundleMode will enable treating the Paths provided as bundles rather than
	// loading all data & policy files.
	BundleMode bool

	// Watch flag controls whether OPA will watch the Paths files for changes.
	// If this flag is true, OPA will watch the Paths files for changes and
	// reload the storage layer each time they change. This is useful for
	// interactive development.
	Watch bool

	// ErrorLimit is the number of errors the compiler will allow to occur before
	// exiting early.
	ErrorLimit int

	// PprofEnabled flag controls whether pprof endpoints are enabled
	PprofEnabled bool

	// DecisionIDFactory generates decision IDs to include in API responses
	// sent by the server (in response to Data API queries.)
	DecisionIDFactory func() string

	// Logging configures the logging behaviour.
	Logging LoggingConfig

	// Logger sets the logger implementation to use for debug logs.
	Logger logging.Logger

	// ConsoleLogger sets the logger implementation to use for console logs.
	ConsoleLogger logging.Logger

	// ConfigFile refers to the OPA configuration to load on startup.
	ConfigFile string

	// ConfigOverrides are overrides for the OPA configuration that are applied
	// over top the config file They are in a list of key=value syntax that
	// conform to the syntax defined in the `strval` package
	ConfigOverrides []string

	// ConfigOverrideFiles Similar to `ConfigOverrides` except they are in the
	// form of `key=path/to/file`where the file contains the value to be used.
	ConfigOverrideFiles []string

	// Output is the output stream used when run as an interactive shell. This
	// is mostly for test purposes.
	Output io.Writer

	// GracefulShutdownPeriod is the time (in seconds) to wait for the http
	// server to shutdown gracefully.
	GracefulShutdownPeriod int

	// ShutdownWaitPeriod is the time (in seconds) to wait before initiating shutdown.
	ShutdownWaitPeriod int

	// EnableVersionCheck flag controls whether OPA will report its version to an external service.
	// If this flag is true, OPA will report its version to the external service
	EnableVersionCheck bool

	// BundleVerificationConfig sets the key configuration used to verify a signed bundle
	BundleVerificationConfig *bundle.VerificationConfig

	// SkipBundleVerification flag controls whether OPA will verify a signed bundle
	SkipBundleVerification bool

	// SkipKnownSchemaCheck flag controls whether OPA will perform type checking on known input schemas
	SkipKnownSchemaCheck bool

	// ReadyTimeout flag controls if and for how long OPA server will wait (in seconds) for
	// configured bundles and plugins to be activated/ready before listening for traffic.
	// A value of 0 or less means no wait is exercised.
	ReadyTimeout int

	// Router is the router to which handlers for the REST API are added.
	// Router uses a first-matching-route-wins strategy, so no existing routes are overridden
	// If it is nil, a new mux.Router will be created
	Router *mux.Router

	// DiskStorage, if set, will make the runtime instantiate a disk-backed storage
	// implementation (instead of the default, in-memory store).
	// It can also be enabled via config, and this runtime field takes precedence.
	DiskStorage *disk.Options

	DistributedTracingOpts tracing.Options

	// Check if default Addr is set or the user has changed it.
	AddrSetByUser bool

	// UnixSocketPerm specifies the permission for the Unix domain socket if used to listen for connections
	UnixSocketPerm *string

	// V0Compatible will enable OPA features and behaviors that were enabled by default in OPA v0.x releases.
	// Takes precedence over V1Compatible.
	V0Compatible bool

	// V1Compatible will enable OPA features and behaviors that will be enabled by default in a future OPA v1.0 release.
	// This flag allows users to opt-in to the new behavior and helps transition to the future release upon which
	// the new behavior will be enabled by default.
	// If V0Compatible is set, V1Compatible will be ignored.
	V1Compatible bool

	// CipherSuites specifies the list of enabled TLS 1.0–1.2 cipher suites
	CipherSuites *[]uint16

	// ReadAstValuesFromStore controls whether the storage layer should return AST values when reading from the store.
	// This is an eager conversion, that comes with an upfront performance cost when updating the store (e.g. bundle updates).
	// Evaluation performance is affected in that data doesn't need to be converted to AST during evaluation.
	// Only applicable when using the default in-memory store, and not when used together with the DiskStorage option.
	ReadAstValuesFromStore bool
}

Params stores the configuration for an OPA instance.

func NewParams

func NewParams() Params

NewParams returns a new Params object.

type Runtime

type Runtime struct {
	Params  Params
	Store   storage.Store
	Manager *plugins.Manager
	// contains filtered or unexported fields
}

Runtime represents a single OPA instance.

func NewRuntime

func NewRuntime(ctx context.Context, params Params) (*Runtime, error)

NewRuntime returns a new Runtime object initialized with params. Clients must call StartServer() or StartREPL() to start the runtime in either mode.

func (*Runtime) Addrs

func (rt *Runtime) Addrs() []string

Addrs returns a list of addresses that the runtime is listening on (when in server mode). Returns an empty list if it hasn't started listening.

func (*Runtime) DiagnosticAddrs

func (rt *Runtime) DiagnosticAddrs() []string

DiagnosticAddrs returns a list of diagnostic addresses that the runtime is listening on (when in server mode). Returns an empty list if it hasn't started listening.

func (*Runtime) Serve

func (rt *Runtime) Serve(ctx context.Context) error

Serve will start a new REST API server and listen for requests. This will block until either: an error occurs, the context is canceled, or a SIGTERM or SIGKILL signal is sent.

func (*Runtime) SetDistributedTracingLogging

func (rt *Runtime) SetDistributedTracingLogging()

SetDistributedTracingLogging configures the distributed tracing's ErrorHandler, and logger instances.

func (*Runtime) StartREPL

func (rt *Runtime) StartREPL(ctx context.Context)

StartREPL starts the runtime in REPL mode. This function will block the calling goroutine.

func (*Runtime) StartServer

func (rt *Runtime) StartServer(ctx context.Context)

StartServer starts the runtime in server mode. This function will block the calling goroutine and will exit the program on error.