storage

Documentation

Overview

Package storage interacts with the permissions-api database handling the metadata updates for roles and resources.

Index

• Variables
• type DB
• type DBQuery
• type Option
  • func WithLogger(logger *zap.SugaredLogger) Option
• type Role
• type RoleBindingService
• type RoleService
• type Storage
  • func New(db DB, options ...Option) Storage
• type TransactionManager
• type ZedTokenService

Variables

var (
	// ErrNoRoleFound is returned when no role is found when retrieving or deleting a role.
	ErrNoRoleFound = errors.New("role not found in database")

	// ErrRoleAlreadyExists is returned when creating a role which already has an existing record.
	ErrRoleAlreadyExists = errors.New("role already exists")

	// ErrRoleNameTaken is returned when the role name provided already exists under the same resource id.
	ErrRoleNameTaken = errors.New("role name already taken")

	// ErrMethodUnavailable is returned when the provided method is called is unavailable in the current environment.
	// For example there is nothing to commit after getting a role so calling Commit on a Role after retrieving it will return this error.
	ErrMethodUnavailable = errors.New("method unavailable")

	// ErrorMissingContextTx represents an error where no context transaction was provided.
	ErrorMissingContextTx = errors.New("no transaction provided in context")

	// ErrorInvalidContextTx represents an error where the given context transaction is of the wrong type.
	ErrorInvalidContextTx = errors.New("invalid type for transaction context")

	// ErrRoleBindingNotFound is returned when no role binding is found when retrieving or deleting a role binding.
	ErrRoleBindingNotFound = errors.New("role binding not found")
)

var Migrations embed.FS

Migrations contains an embedded filesystem with all the sql migration files

Types

type DB

type DB interface {
	BeginTx(ctx context.Context, opts *sql.TxOptions) (*sql.Tx, error)
	PingContext(ctx context.Context) error

	DBQuery
}

DB is the interface the database package requires from a database engine to run. *sql.DB implements these methods.

type DBQuery

type DBQuery interface {
	QueryContext(ctx context.Context, query string, args ...any) (*sql.Rows, error)
	QueryRowContext(ctx context.Context, query string, args ...any) *sql.Row
	ExecContext(ctx context.Context, query string, args ...any) (sql.Result, error)
}

DBQuery are required methods for querying the database.

type Option

type Option func(e *engine)

Option defines a storage engine configuration option.

func WithLogger

func WithLogger(logger *zap.SugaredLogger) Option

WithLogger sets the logger for the storage engine.

type Role

type Role struct {
	ID         gidx.PrefixedID
	Name       string
	Manager    string
	ResourceID gidx.PrefixedID
	CreatedBy  gidx.PrefixedID
	UpdatedBy  gidx.PrefixedID
	CreatedAt  time.Time
	UpdatedAt  time.Time
}

Role represents a role in the database.

type RoleBindingService

type RoleBindingService interface {
	// ListResourceRoleBindings returns all role bindings for a given resource
	// an empty slice is returned if no role bindings are found
	ListResourceRoleBindings(ctx context.Context, resourceID gidx.PrefixedID) ([]types.RoleBinding, error)

	// ListManagerResourceRoleBindings returns all role bindings for a given resource and manager
	// an empty slice is returned if no role bindings are found
	ListManagerResourceRoleBindings(ctx context.Context, manager string, resourceID gidx.PrefixedID) ([]types.RoleBinding, error)

	// GetRoleBindingByID returns a role binding by its prefixed ID
	// an ErrRoleBindingNotFound error is returned if no role binding is found
	GetRoleBindingByID(ctx context.Context, id gidx.PrefixedID) (types.RoleBinding, error)

	// CreateRoleBinding creates a new role binding in the database
	// This method must be called with a context returned from BeginContext.
	// CommitContext or RollbackContext must be called afterwards if this method returns no error.
	CreateRoleBinding(ctx context.Context, actorID, rbID, resourceID gidx.PrefixedID, manager string) (types.RoleBinding, error)

	// UpdateRoleBinding updates a role binding in the database
	// Note that this method only updates the updated_at and updated_by fields
	// and do not provide a way to update the resource_id field.
	//
	// This method must be called with a context returned from BeginContext.
	// CommitContext or RollbackContext must be called afterwards if this method returns no error.
	UpdateRoleBinding(ctx context.Context, actorID, rbID gidx.PrefixedID) (types.RoleBinding, error)

	// DeleteRoleBinding deletes a role binding from the database
	// This method must be called with a context returned from BeginContext.
	// CommitContext or RollbackContext must be called afterwards if this method returns no error.
	DeleteRoleBinding(ctx context.Context, id gidx.PrefixedID) error

	// LockRoleBindingForUpdate locks a role binding record to be updated to ensure consistency.
	// If the role binding is not found, an ErrRoleBindingNotFound error is returned.
	LockRoleBindingForUpdate(ctx context.Context, id gidx.PrefixedID) error
}

RoleBindingService represents a service for managing role bindings in the permissions API storage

type RoleService

type RoleService interface {
	GetRoleByID(ctx context.Context, id gidx.PrefixedID) (Role, error)
	GetResourceRoleByName(ctx context.Context, resourceID gidx.PrefixedID, name string) (Role, error)
	ListResourceRoles(ctx context.Context, resourceID gidx.PrefixedID) ([]Role, error)
	ListManagerResourceRoles(ctx context.Context, manager string, resourceID gidx.PrefixedID) ([]Role, error)
	CreateRole(ctx context.Context, actorID gidx.PrefixedID, roleID gidx.PrefixedID, name string, manager string, resourceID gidx.PrefixedID) (Role, error)
	UpdateRole(ctx context.Context, actorID, roleID gidx.PrefixedID, name string) (Role, error)
	DeleteRole(ctx context.Context, roleID gidx.PrefixedID) (Role, error)
	LockRoleForUpdate(ctx context.Context, roleID gidx.PrefixedID) error
	BatchGetRoleByID(ctx context.Context, ids []gidx.PrefixedID) ([]Role, error)
}

RoleService represents a service for managing roles.

type Storage

type Storage interface {
	RoleService
	RoleBindingService
	ZedTokenService
	TransactionManager

	HealthCheck(ctx context.Context) error
}

Storage defines the interface the engine exposes.

func New

func New(db DB, options ...Option) Storage

New creates a new storage engine using the provided underlying DB.

type TransactionManager

type TransactionManager interface {
	BeginContext(context.Context) (context.Context, error)
	CommitContext(context.Context) error
	RollbackContext(context.Context) error
}

TransactionManager manages the state of sql transactions within a context

type ZedTokenService

type ZedTokenService interface {
	GetLatestZedToken(ctx context.Context, ids ...gidx.PrefixedID) (string, error)
	UpsertZedToken(ctx context.Context, id gidx.PrefixedID, zedToken string) error
}

ZedTokenService represents a service for getting and updating ZedTokens for resources.