topology

package
v14.52.0 Latest Latest
Warning

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

Go to latest
Published: May 19, 2026 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

Package topology provides a client for interacting with the GitLab Cells Topology Service.

The Topology Service is a gRPC server that provides cell routing information for requests related to specific records (projects, groups, etc.) in a GitLab Cells architecture.

Configuration is done via the topology_service section in config.yml:

topology_service:
  enabled: true
  address: "topology.gitlab.com:443"
  tls:
    enabled: true
    ca_file: "/path/to/ca.crt"

For more details, see:

Index

Constants

View Source
const DefaultTimeout = 5 * time.Second

DefaultTimeout is the default timeout for Topology Service requests.

Variables

This section is empty.

Functions

func ExtractTopLevelNamespace added in v14.50.0

func ExtractTopLevelNamespace(repo string) string

ExtractTopLevelNamespace returns the first path segment from a repository path (the top-level namespace in GitLab). Examples:

  • "group/project.git" → "group"
  • "group" → "group" (single-segment paths are valid for top-level namespaces)
  • "" → ""

func ProjectIDClaim added in v14.50.0

func ProjectIDClaim(id int64) *types_proto.Claim

ProjectIDClaim creates a Claim for a project ID.

func RouteClaim added in v14.50.0

func RouteClaim(route string) *types_proto.Claim

RouteClaim creates a Claim for a GitLab top-level route (e.g., "my-group"). Only top-level paths (without "/") are claimed in the Topology Service; sub-routes like "my-group/my-project" are derived from their parent and should not be used as classification keys.

func SSHKeyClaim added in v14.50.0

func SSHKeyClaim(key string) *types_proto.Claim

SSHKeyClaim creates a Claim for an SSH public key.

func UsernameClaim added in v14.51.0

func UsernameClaim(username string) *types_proto.Claim

UsernameClaim creates a Claim for a GitLab username. Callers should not pass an empty string; the resolver guards against this, but calling UsernameClaim("") directly would send an empty claim to the Topology Service.

Types

type Client added in v14.47.0

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

Client provides a gRPC client for the Topology Service. It handles connection management with lazy initialization and supports TLS/mTLS for secure connections.

func NewClient added in v14.47.0

func NewClient(cfg *Config) *Client

NewClient creates a new Topology Service client from the given configuration. Returns nil if the topology service is disabled in the configuration. The client uses lazy initialization - the actual gRPC connection is established on the first call to Classify. The configuration is copied to avoid mutating the original.

func (*Client) Classify added in v14.47.0

func (c *Client) Classify(ctx context.Context, claim *types_proto.Claim) (resp *pb.ClassifyResponse, err error)

Classify queries the Topology Service to determine which cell should handle the resource identified by the given claim. Claims support typed lookups such as routes, SSH keys, project IDs, etc.

func (*Client) Close added in v14.47.0

func (c *Client) Close() error

Close closes the gRPC connection to the Topology Service. It is safe to call Close multiple times.

type Config

type Config struct {
	// Enabled indicates whether Topology Service integration is enabled.
	Enabled bool `yaml:"enabled"`

	// Address is the gRPC address of the Topology Service (e.g., "topology.gitlab.com:443").
	Address string `yaml:"address"`

	// Timeout is the maximum duration to wait for a response from the Topology Service.
	// Default: 5s (when zero).
	Timeout time.Duration `yaml:"timeout"`

	// TLS contains TLS configuration for secure connections.
	TLS TLSConfig `yaml:"tls"`
}

Config contains Topology Service client configuration settings.

func (*Config) Validate

func (c *Config) Validate() error

Validate validates the Topology Service configuration.

type Resolver added in v14.50.0

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

Resolver queries the Topology Service to determine which cell should handle a request. It gracefully degrades: if the TS is disabled, unreachable, or returns an error, an empty string is returned and the caller should use the default host.

func NewResolver added in v14.50.0

func NewResolver(client *Client, gitlabURL string) *Resolver

NewResolver creates a new Resolver. If client is nil (TS disabled), all resolve calls return empty string immediately. The gitlabURL is used to infer the URL scheme (http or https) for schemaless addresses returned by the Topology Service.

func (*Resolver) ClientForRoute added in v14.50.0

func (r *Resolver) ClientForRoute(ctx context.Context, httpClient *client.GitlabNetClient, repoPath string) RoutedClient

ClientForRoute resolves the cell that owns repoPath and returns a RoutedClient. When the Topology Service is not configured, returns an error, or returns a non-PROXY action, Address is empty and Client is the original httpClient.

func (*Resolver) ClientForSSHKey added in v14.50.0

func (r *Resolver) ClientForSSHKey(ctx context.Context, httpClient *client.GitlabNetClient, key string) RoutedClient

ClientForSSHKey resolves the cell that owns key and returns a RoutedClient. When the Topology Service is not configured, returns an error, or returns a non-PROXY action, Address is empty and Client is the original httpClient.

func (*Resolver) ClientForUserArgs added in v14.51.0

func (r *Resolver) ClientForUserArgs(ctx context.Context, httpClient *client.GitlabNetClient, args UserArgs) RoutedClient

ClientForUserArgs resolves the cell that owns the user identity in args and returns a RoutedClient. When the Topology Service is not configured, returns an error, or returns a non-PROXY action, Address is empty and Client is the original httpClient.

type RoutedClient added in v14.52.0

type RoutedClient struct {
	Client  *client.GitlabNetClient
	Address string
}

RoutedClient holds an HTTP client that may have been routed to a specific cell, along with that cell's address. When the Topology Service is not configured or returned a non-PROXY response, Address is empty and Client is the original unmodified client.

Obtain via Resolver.ClientForSSHKey, Resolver.ClientForRoute, or Resolver.ClientForUserArgs; the zero value is not valid for use.

type TLSConfig

type TLSConfig struct {
	// Enabled indicates whether TLS should be used for the connection.
	Enabled bool `yaml:"enabled"`

	// CAFile is the path to the CA certificate file for server verification.
	// If empty, system CA certificates will be used.
	CAFile string `yaml:"ca_file"`

	// CertFile is the path to the client certificate file (for mTLS).
	// Must be provided together with KeyFile.
	CertFile string `yaml:"cert_file"`

	// KeyFile is the path to the client key file (for mTLS).
	// Must be provided together with CertFile.
	KeyFile string `yaml:"key_file"`

	// ServerName is the expected server name for TLS verification.
	// If empty, the hostname from Address will be used.
	ServerName string `yaml:"server_name"`

	// InsecureSkipVerify skips TLS certificate verification.
	// WARNING: This should only be used for development/testing.
	InsecureSkipVerify bool `yaml:"insecure_skip_verify"`
}

TLSConfig contains TLS settings for the Topology Service connection.

func (*TLSConfig) Validate

func (c *TLSConfig) Validate() error

Validate validates the TLS configuration.

type UserArgs added in v14.51.0

type UserArgs struct {
	Username      string
	KeyID         string
	Krb5Principal string
}

UserArgs holds the user identity fields needed for cell resolution. It mirrors the relevant fields from commandargs.Shell but avoids importing the command layer into the topology package.

Directories

Path Synopsis
Package topologytest provides shared test helpers for the Topology Service mock gRPC server.
Package topologytest provides shared test helpers for the Topology Service mock gRPC server.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL