namespaces

package
v1.38.0-rc.0 Latest Latest
Warning

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

 Go to latest Published: May 27, 2026 License: BSD-3-Clause Imports: 9 Imported by: 0

Documentation

Overview

Package namespaces owns the namespace control-plane state and exposes a typed domain API for callers that need direct existence checks without reaching for RAFT subcommand types.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrBadRequest signals a malformed RAFT command payload or an invalid
	// argument so the apply path can classify it distinctly from
	// legitimate-but-rejected operations.
	ErrBadRequest = errors.New("bad request")

	// ErrAlreadyExists is returned by Create when a namespace with the given
	// name is already present. Callers that need a distinct status for
	// duplicates (e.g. an HTTP handler mapping to 409) should check with
	// errors.Is rather than string-matching the error message.
	ErrAlreadyExists = errors.New("namespace already exists")

	// ErrNotFound is returned by ChangeState and RemoveEntity when the
	// target namespace does not exist. Callers that need a distinct status
	// for missing entries (e.g. an HTTP handler mapping to 404) should
	// check with errors.Is.
	ErrNotFound = errors.New("namespace not found")

	// ErrNamespaceDeleting is returned when a create-like operation targets
	// a namespace that exists but is currently being torn down. Distinct
	// from ErrAlreadyExists so REST can render a different conflict message.
	ErrNamespaceDeleting = errors.New("namespace is being deleted")

	// ErrNamespaceGone is returned by apply-time checks when a namespace
	// the caller validated earlier no longer exists.
	ErrNamespaceGone = errors.New("namespace no longer exists")

	// ErrNamespaceNotEmpty is returned by RemoveEntity at the apply layer
	// when the namespace still owns classes, aliases, or DB users.
	ErrNamespaceNotEmpty = errors.New("namespace still has owned resources")

	// ErrInvalidState is a defense-in-depth sentinel for operations called
	// on a namespace whose current state forbids them (e.g. RemoveEntity on
	// an active namespace).
	ErrInvalidState = errors.New("namespace is in an invalid state for this operation")

	// ErrInvalidStateTransition is returned by ChangeState when the target
	// state is unreachable from the namespace's current state.
	ErrInvalidStateTransition = errors.New("invalid namespace state transition")
)

Functions

func ValidateName 

func ValidateName(name string) error

ValidateName enforces the package's naming contract. It is the single source of truth for namespace name validation and is called both from the REST handler (for fast 422 rejection without a RAFT round-trip) and from the apply path (as a defense-in-depth check).

Types

type Controller 

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

Controller owns the namespace control-plane state.

Concurrency contract: hashicorp RAFT invokes Snapshot from a goroutine that may run concurrently with Apply, so the RLock inside Snapshot is load-bearing, not cosmetic. Applies are serialized by RAFT (write-lock semantics); queries take the read-lock. Do not remove the Snapshot RLock in a future refactor.

func NewController 

func NewController(logger logrus.FieldLogger) *Controller

NewController returns an empty, ready-to-use controller.

func (*Controller) ChangeState 

func (c *Controller) ChangeState(name string, target cmd.NamespaceState) error

ChangeState transitions a namespace into target. Same-state transitions are idempotent and return nil. Returns ErrBadRequest when target is not a recognized state, ErrNotFound when the namespace does not exist, and ErrInvalidStateTransition when the transition is forbidden (e.g. deleting back to active).

func (*Controller) Count 

func (c *Controller) Count() int

Count returns the number of known namespaces. Used by the startup invariant check.

func (*Controller) Create 

func (c *Controller) Create(ns cmd.Namespace) error

Create inserts a namespace in the cmd.NamespaceStateActive state; the input's State is ignored. HomeNodes must contain exactly one non-empty entry — downstream placement and counters rely on that invariant. Returns ErrBadRequest for invalid names or HomeNodes, ErrAlreadyExists when the name maps to an active namespace, and ErrNamespaceDeleting when the name is currently being torn down.

func (*Controller) Exists 

func (c *Controller) Exists(name string) bool

Exists reports whether a namespace with the given name is known. Intended for non-cluster callers (REST handlers, OIDC claim resolution) that need a fast existence check without constructing a RAFT subcommand. Returns true for entries in any state.

func (*Controller) Get 

func (c *Controller) Get(names ...string) []cmd.Namespace

Get returns the named namespaces. An empty Names slice returns all known namespaces; otherwise only the named ones that exist are returned (missing names are silently omitted).

func (*Controller) GetNamespace 

func (c *Controller) GetNamespace(name string) (ns cmd.Namespace, ok bool)

GetNamespace returns a snapshot copy of the namespace by name. ok is false when the namespace does not exist.

func (*Controller) IsActive 

func (c *Controller) IsActive(name string) bool

IsActive reports whether the named namespace exists and is in the cmd.NamespaceStateActive state.

func (*Controller) List 

func (c *Controller) List() []cmd.Namespace

List returns a snapshot copy of all namespaces. Intended for callers that need to iterate without holding the lock.

func (*Controller) ListDeleting 

func (c *Controller) ListDeleting() []string

ListDeleting returns the names of namespaces currently in the deleting state, sorted lexicographically.

func (*Controller) RemoveEntity 

func (c *Controller) RemoveEntity(name string) error

RemoveEntity removes the namespace map entry. Callable only on a namespace already marked for deletion; an active namespace returns ErrInvalidState. Returns ErrNotFound when the namespace does not exist.

func (*Controller) Restore 

func (c *Controller) Restore(snapshot []byte) error

Restore replaces the current state with the snapshot contents. A nil or empty snapshot leaves state empty (fresh bootstrap). Unknown JSON fields are tolerated. Entries with empty State are normalized to cmd.NamespaceStateActive; entries with an unknown State return an error so a future binary's snapshot is not silently mis-classified. Entries missing the single HomeNodes entry are also rejected — there is no migration path from a pre-HomeNodes snapshot.

func (*Controller) Snapshot 

func (c *Controller) Snapshot() ([]byte, error)

Snapshot serializes the entire namespace map. See the Controller godoc for why the read lock is required even though Apply is single-threaded.

func (*Controller) Update 

func (c *Controller) Update(ns cmd.Namespace) error

Update overwrites the stored HomeNodes for an existing namespace. HomeNodes must contain exactly one non-empty entry; Name and State are immutable here. Returns ErrBadRequest for an invalid HomeNodes, ErrNotFound when the namespace does not exist, and ErrNamespaceDeleting when the namespace is being torn down.

type Exister 

type Exister interface {
	Exists(name string) bool
	IsActive(name string) bool
	GetNamespace(name string) (cmd.Namespace, bool)
}

Exister exposes read-only access to namespace state. Exists matches any state; IsActive excludes the deleting state.

type MockExister 

type MockExister struct {
	mock.Mock
}

MockExister is an autogenerated mock type for the Exister type

func NewMockExister 

func NewMockExister(t interface {
	mock.TestingT
	Cleanup(func())
}) *MockExister

NewMockExister creates a new instance of MockExister. It also registers a testing interface on the mock and a cleanup function to assert the mocks expectations. The first argument is typically a *testing.T value.

func (*MockExister) EXPECT 

func (_m *MockExister) EXPECT() *MockExister_Expecter

func (*MockExister) Exists 

func (_m *MockExister) Exists(name string) bool

Exists provides a mock function with given fields: name

func (*MockExister) GetNamespace 

func (_m *MockExister) GetNamespace(name string) (api.Namespace, bool)

GetNamespace provides a mock function with given fields: name

func (*MockExister) IsActive 

func (_m *MockExister) IsActive(name string) bool

IsActive provides a mock function with given fields: name

type MockExister_Exists_Call 

type MockExister_Exists_Call struct {
	*mock.Call
}

MockExister_Exists_Call is a *mock.Call that shadows Run/Return methods with type explicit version for method 'Exists'

func (*MockExister_Exists_Call) Return 

func (_c *MockExister_Exists_Call) Return(_a0 bool) *MockExister_Exists_Call

func (*MockExister_Exists_Call) Run 

func (_c *MockExister_Exists_Call) Run(run func(name string)) *MockExister_Exists_Call

func (*MockExister_Exists_Call) RunAndReturn 

func (_c *MockExister_Exists_Call) RunAndReturn(run func(string) bool) *MockExister_Exists_Call

type MockExister_Expecter 

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

func (*MockExister_Expecter) Exists 

func (_e *MockExister_Expecter) Exists(name interface{}) *MockExister_Exists_Call

Exists is a helper method to define mock.On call

  • name string

func (*MockExister_Expecter) GetNamespace 

func (_e *MockExister_Expecter) GetNamespace(name interface{}) *MockExister_GetNamespace_Call

GetNamespace is a helper method to define mock.On call

  • name string

func (*MockExister_Expecter) IsActive 

func (_e *MockExister_Expecter) IsActive(name interface{}) *MockExister_IsActive_Call

IsActive is a helper method to define mock.On call

  • name string

type MockExister_GetNamespace_Call 

type MockExister_GetNamespace_Call struct {
	*mock.Call
}

MockExister_GetNamespace_Call is a *mock.Call that shadows Run/Return methods with type explicit version for method 'GetNamespace'

func (*MockExister_GetNamespace_Call) Return 

func (_c *MockExister_GetNamespace_Call) Return(_a0 api.Namespace, _a1 bool) *MockExister_GetNamespace_Call

func (*MockExister_GetNamespace_Call) Run 

func (_c *MockExister_GetNamespace_Call) Run(run func(name string)) *MockExister_GetNamespace_Call

func (*MockExister_GetNamespace_Call) RunAndReturn 

func (_c *MockExister_GetNamespace_Call) RunAndReturn(run func(string) (api.Namespace, bool)) *MockExister_GetNamespace_Call

type MockExister_IsActive_Call 

type MockExister_IsActive_Call struct {
	*mock.Call
}

MockExister_IsActive_Call is a *mock.Call that shadows Run/Return methods with type explicit version for method 'IsActive'

func (*MockExister_IsActive_Call) Return 

func (_c *MockExister_IsActive_Call) Return(_a0 bool) *MockExister_IsActive_Call

func (*MockExister_IsActive_Call) Run 

func (_c *MockExister_IsActive_Call) Run(run func(name string)) *MockExister_IsActive_Call

func (*MockExister_IsActive_Call) RunAndReturn 

func (_c *MockExister_IsActive_Call) RunAndReturn(run func(string) bool) *MockExister_IsActive_Call

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.