testutil

Documentation

Overview

Package testutil provides testing utilities such as functions to start a Cerbos server and tear it down.

Index

• type ServerInfo
  • func StartCerbosServer(opts ...ServerOpt) (*ServerInfo, error)
  • func (s *ServerInfo) GRPCAddr() string
  • func (s *ServerInfo) HTTPAddr() string
  • func (s *ServerInfo) IsReady(ctx context.Context) (bool, error)
  • func (s *ServerInfo) Stop() error
• type ServerOpt
  • func WithAdminAPI(username, password string) ServerOpt
  • func WithConfig(src io.Reader) ServerOpt
  • func WithConfigKeyValue(key, value string) ServerOpt
  • func WithDefaultPolicyVersion(version string) ServerOpt
  • func WithGRPCListenAddr(grpcListenAddr string) ServerOpt
  • func WithHTTPListenAddr(httpListenAddr string) ServerOpt
  • func WithPolicyRepositoryDirectory(dir string) ServerOpt
  • func WithPolicyRepositorySQLite3(dsn string) ServerOpt
  • func WithTLSCACert(caCert string) ServerOpt
  • func WithTLSCertAndKey(cert, key string) ServerOpt

Examples

• StartCerbosServer

Types

type ServerInfo

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

func StartCerbosServer

func StartCerbosServer(opts ...ServerOpt) (*ServerInfo, error)

StartCerbosServer starts a new Cerbos server that can be used for testing a client integration locally with test data. If no options are passed, the server will be started with the http and gRPC endpoints available on a random free port and the storage backend configured to use an in-memory database. Use the methods on the returned ServerInfo object to find the listening addresses and stop the server when tests are done.

Example

package main

import (
	"context"
	"fmt"
	"log"

	"github.com/cerbos/cerbos/client"
	"github.com/cerbos/cerbos/client/testutil"
)

func main() {
	s, err := testutil.StartCerbosServer()
	if err != nil {
		log.Fatalf("Failed to start Cerbos server: %v", err)
	}

	defer s.Stop()

	c, err := client.New(s.GRPCAddr(), client.WithPlaintext())
	if err != nil {
		log.Fatalf("Failed to create Cerbos client: %v", err)
	}

	resp, err := c.CheckResourceSet(
		context.TODO(),
		client.NewPrincipal("john").
			WithRoles("employee", "manager").
			WithAttr("department", "marketing").
			WithAttr("geography", "GB"),
		client.NewResourceSet("leave_request").
			AddResourceInstance("XX125", map[string]any{
				"department": "marketing",
				"geography":  "GB",
				"owner":      "harry",
				"status":     "DRAFT",
			}),
		"view", "approve")
	if err != nil {
		log.Fatalf("API request failed: %v", err)
	}

	fmt.Println(resp.IsAllowed("XX125", "view"))
}

Output:

false

func (*ServerInfo) GRPCAddr

func (s *ServerInfo) GRPCAddr() string

GRPCAddr returns the GRPC listen address of the running server.

func (*ServerInfo) HTTPAddr

func (s *ServerInfo) HTTPAddr() string

HTTPAddr returns the HTTP listen address of the running server.

func (*ServerInfo) IsReady

func (s *ServerInfo) IsReady(ctx context.Context) (bool, error)

IsReady returns true if the server health check is successful.

func (*ServerInfo) Stop

func (s *ServerInfo) Stop() error

Stop the running server.

type ServerOpt

type ServerOpt func(*serverOpt)

func WithAdminAPI

func WithAdminAPI(username, password string) ServerOpt

WithAdminAPI enables the AdminAPI with the given username and password. Defaults to disabled.

func WithConfig

func WithConfig(src io.Reader) ServerOpt

WithConfig sets the source to read Cerbos configuration data.

func WithConfigKeyValue

func WithConfigKeyValue(key, value string) ServerOpt

WithConfigKeyValue sets the given config key to the provided value.

func WithDefaultPolicyVersion

func WithDefaultPolicyVersion(version string) ServerOpt

WithDefaultPolicyVersion sets the default policy version to use when none is specified. Default to the "default".

func WithGRPCListenAddr

func WithGRPCListenAddr(grpcListenAddr string) ServerOpt

WithGRPCListenAddr sets the listener address for gRPC. Default is to find a random, unused port.

func WithHTTPListenAddr

func WithHTTPListenAddr(httpListenAddr string) ServerOpt

WithHTTPListenAddr sets the listener address for HTTP. Default is to find a random, unused port.

func WithPolicyRepositoryDirectory

func WithPolicyRepositoryDirectory(dir string) ServerOpt

WithPolicyRepositoryDirectory sets the directory to use as the policy repository. Defaults to none. Cannot be used together with WithPolicyRepositorySQLite3.

func WithPolicyRepositorySQLite3

func WithPolicyRepositorySQLite3(dsn string) ServerOpt

WithPolicyRepositorySQLite3 sets the policy repository to the given SQLite3 database. Cannot be used together with WithPolicyRepositoryDirectory.

func WithTLSCACert

func WithTLSCACert(caCert string) ServerOpt

WithTLSCACert sets the TLS CA certicate to use. Defaults to none.

func WithTLSCertAndKey

func WithTLSCertAndKey(cert, key string) ServerOpt

WithTLSCertAndKey sets the TLS certificate and key to use. Defaults to no TLS.