servicequery

Documentation

Overview

Package servicequery compiles one authorized service scope into an exact repository, revision, and placement predicate for zoekt. It does not open a reader or expose a product surface; T34.3 owns the generation-bound reader.

Index

• Constants
• Variables
• func ConfirmRuntimeScope(ctx context.Context, indexDir string, st RuntimeStore, scope RuntimeScope) error
• func ValidateAuthority(authority Authority) error
• type Authority
  • func DecodeAuthority(encoded []byte) (Authority, error)
  • func (authority Authority) Canonical() ([]byte, error)
• type Compiled
  • func Compile(request Request) (Compiled, error)
• type GenerationStore
• type PreparedScope
  • func Prepare(scope Scope) (PreparedScope, error)
• type ReconcileOutcome
  • func ReconcileGeneration(ctx context.Context, indexDir string, st GenerationStore, repository string) (ReconcileOutcome, error)
• type Request
• type RuntimeScope
  • func OpenRuntimeScope(ctx context.Context, indexDir string, st RuntimeStore, ...) (RuntimeScope, error)
  • func (scope RuntimeScope) Prepared() (PreparedScope, bool)
  • func (scope RuntimeScope) Search() (repositoryindex.SearchManifest, bool)
• type RuntimeStore
• type Scope

Constants

const (
	AuthoritySchema = "phebs-service-query-authority-v1"
	PredicatePolicy = "exact-service-placement-prefix-v1"

	// MaxExpressionBytes bounds parsing and the expression identity retained by
	// one compiled request. Transport body limits may be smaller.
	MaxExpressionBytes = 16 << 10
	MaxAuthorityBytes  = 16 << 10
	// regexp.QuoteMeta can at most double the admitted path bytes. Each exact
	// path atom adds the fixed ^(?:...)(?:/|$) envelope.
	MaxPredicateBytes = 2*servicecatalog.MaxServicePathBytes +
		servicecatalog.MaxServicePaths*len("^(?:)(?:/|$)")
)

Variables

var (
	ErrInvalidScope           = errors.New("invalid service query scope")
	ErrInvalidExpression      = errors.New("invalid service query expression")
	ErrUnsupportedComposition = errors.New("unsupported service query composition")
	ErrUnavailable            = errors.New("service query scope unavailable")
)

Functions

func ConfirmRuntimeScope

func ConfirmRuntimeScope(
	ctx context.Context,
	indexDir string,
	st RuntimeStore,
	scope RuntimeScope,
) error

ConfirmRuntimeScope is the pre-emission linearization point. It rereads only the repository row, catalog/summary points, and bounded v2 control files; a publication, rollback, restore, removal, or state transition discards the complete result.

func ValidateAuthority

func ValidateAuthority(authority Authority) error

ValidateAuthority verifies a decoded query/cursor identity without needing the original query object.

Types

type Authority

type Authority struct {
	Schema                     string `json:"schema"`
	PredicatePolicy            string `json:"predicate_policy"`
	TopologyPolicy             string `json:"topology_policy"`
	Repository                 string `json:"repository"`
	ServiceKey                 string `json:"service_key"`
	Status                     string `json:"status"`
	Incarnation                uint64 `json:"incarnation"`
	RevisionSelector           string `json:"revision_selector"`
	RevisionBranch             string `json:"revision_branch"`
	RevisionCommit             string `json:"revision_commit"`
	ExpressionDigest           string `json:"expression_digest"`
	CurrentCatalogGeneration   string `json:"current_catalog_generation"`
	CatalogControlRevision     uint64 `json:"catalog_control_revision"`
	ActiveCatalogGeneration    string `json:"active_catalog_generation"`
	ActiveSourceGeneration     string `json:"active_source_generation"`
	ActiveDesiredGeneration    string `json:"active_desired_generation"`
	ServiceStateDigest         string `json:"service_state_digest"`
	ServiceStateRevision       uint64 `json:"service_state_revision"`
	StateSummaryDigest         string `json:"state_summary_digest"`
	StateSummaryRevision       uint64 `json:"state_summary_revision"`
	RepositorySourceGeneration string `json:"repository_source_generation"`
	RepositorySearchGeneration string `json:"repository_search_generation"`
	PathDigest                 string `json:"path_digest"`
	PathCount                  int    `json:"path_count"`
	PathBytes                  int    `json:"path_bytes"`
	PredicateAtoms             int    `json:"predicate_atoms"`
	PredicateBytes             int    `json:"predicate_bytes"`
	Digest                     string `json:"digest"`
}

Authority is the closed query/cursor identity. Current catalog and state fences invalidate continuations after lifecycle changes; active identities and T34.1 roots prevent an older reader from relabeling results.

func DecodeAuthority

func DecodeAuthority(encoded []byte) (Authority, error)

DecodeAuthority accepts only the exact canonical closed form. Requiring byte equality after a strict decode rejects duplicate fields, alternate ordering/whitespace, unknown fields, and trailing values at one boundary.

func (Authority) Canonical

func (authority Authority) Canonical() ([]byte, error)

Canonical returns the deterministic closed JSON used by a future transport cursor. It validates all bounds and the digest before returning bytes.

type Compiled

type Compiled struct {
	Query     query.Q
	Authority Authority
}

Compiled is one pre-ranking zoekt query plus its closed authority receipt. Query already contains repository, exact branch, and path predicates; a caller must not apply result-time service filtering.

func Compile

func Compile(request Request) (Compiled, error)

Compile parses one expression and allocates bounded predicates from an already prepared scope.

type GenerationStore

type GenerationStore interface {
	GetRepo(context.Context, string) (*store.Repo, error)
	GetServiceCatalog(context.Context, string) (*servicecatalog.Publication, error)
	ServiceGenerationActivationNeeded(context.Context, string, string, string, string) (bool, error)
	ActivateServiceGeneration(context.Context, string, string, string, string) (int, error)
}

GenerationStore is the bounded state transition used after an exact direct search publication or during startup backfill.

type PreparedScope

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

PreparedScope is an opaque, fully verified placement and generation authority. Callers may cache it only under its embedded state/search fences; compiling another expression or indexed selector then performs no catalog decode, source-member read, shard read, or placement reconstruction.

func Prepare

func Prepare(scope Scope) (PreparedScope, error)

Prepare validates every catalog/state/search binding and derives the exact active placement set once. Current and active catalog generations are each decoded at most once; equal generations share the verified decode.

type ReconcileOutcome

type ReconcileOutcome struct {
	Activated int
	Current   bool
	Search    repositoryindex.SearchManifest
}

func ReconcileGeneration

func ReconcileGeneration(
	ctx context.Context,
	indexDir string,
	st GenerationStore,
	repository string,
) (ReconcileOutcome, error)

ReconcileGeneration validates a replacement completely before atomically activating every accepted desired service. An already-current generation takes the bounded control-only path; it never rereads source members.

type Request

type Request struct {
	Expression       string
	RevisionSelector string
	Scopes           []PreparedScope
}

Request carries the already authorized scopes to compile. Initial v2 accepts exactly one repository-local scope; using a slice makes the future cross-repository boundary explicit rather than silently choosing one.

type RuntimeScope

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

RuntimeScope is an opaque strict-open store/filesystem snapshot. Its prepared compiler input and search root remain immutable copies; callers must final-fence the scope before any result escapes.

func OpenRuntimeScope

func OpenRuntimeScope(
	ctx context.Context,
	indexDir string,
	st RuntimeStore,
	repository, serviceKey string,
) (RuntimeScope, error)

OpenRuntimeScope strict-opens current catalog/state, the exact historical active catalog when stale, and the current direct v2 search controls. Full member hashing belongs to the generation cache fill; this hot boundary reads only bounded control files and precious point rows.

func (RuntimeScope) Prepared

func (scope RuntimeScope) Prepared() (PreparedScope, bool)

func (RuntimeScope) Search

func (scope RuntimeScope) Search() (repositoryindex.SearchManifest, bool)

type RuntimeStore

type RuntimeStore interface {
	GetRepo(context.Context, string) (*store.Repo, error)
	GetServiceStateRead(context.Context, string, string) (*store.ServiceStateRead, error)
	GetServiceCatalogGeneration(context.Context, string, string) (*servicecatalog.Publication, error)
	ConfirmServiceStateSnapshot(context.Context, string, servicecatalog.RepositoryState) error
}

RuntimeStore is the narrow precious-state boundary required to open and final-fence one service-scoped search. Authorization remains the caller's responsibility and must happen before invoking OpenRuntimeScope.

type Scope

type Scope struct {
	CurrentCatalog servicecatalog.Publication
	ActiveCatalog  servicecatalog.Publication
	Summary        servicecatalog.RepositoryState
	State          servicecatalog.ServiceState
	Search         repositoryindex.SearchManifest
}

Scope is the complete authority needed to derive a service's active placement set. CurrentCatalog and Summary fence the request/cursor snapshot; ActiveCatalog may be an older immutable generation for an explicitly stale service. Search is the strict-open T34.1 root the later reader must hold.