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
- func ExtractTopLevelNamespace(repo string) string
- func ProjectIDClaim(id int64) *types_proto.Claim
- func RouteClaim(route string) *types_proto.Claim
- func SSHKeyClaim(key string) *types_proto.Claim
- type Client
- type Config
- type Resolver
- func (r *Resolver) ClientForRoute(ctx context.Context, httpClient *client.GitlabNetClient, repoPath string) *client.GitlabNetClient
- func (r *Resolver) ClientForSSHKey(ctx context.Context, httpClient *client.GitlabNetClient, key string) *client.GitlabNetClient
- func (r *Resolver) Resolve(ctx context.Context, claim *types_proto.Claim) string
- func (r *Resolver) ResolveByRoute(ctx context.Context, repoPath string) string
- func (r *Resolver) ResolveBySSHKey(ctx context.Context, key string) string
- type TLSConfig
Constants ¶
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
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.
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
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.
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.
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
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) *client.GitlabNetClient
ClientForRoute returns httpClient routed to the cell resolved for repoPath, or the original httpClient if the Topology Service is not configured, returns an error, or returns a non-PROXY action.
func (*Resolver) ClientForSSHKey ¶ added in v14.50.0
func (r *Resolver) ClientForSSHKey(ctx context.Context, httpClient *client.GitlabNetClient, key string) *client.GitlabNetClient
ClientForSSHKey returns httpClient routed to the cell resolved for key, or the original httpClient if the Topology Service is not configured, returns an error, or returns a non-PROXY action.
func (*Resolver) Resolve ¶ added in v14.50.0
Resolve queries the Topology Service with the given claim and returns the proxy address as an HTTP(S) URL string. The scheme is inferred from the original GitLab URL when the Topology Service returns a schemaless address. Returns empty string on any failure or when TS is not configured. Transient errors are retried with exponential backoff.
func (*Resolver) ResolveByRoute ¶ added in v14.50.0
ResolveByRoute resolves a cell address from a repository path. It extracts the top-level namespace and creates a RouteClaim. Suitable for repo-scoped endpoints: /allowed, /lfs_authenticate, /git_audit_event.
func (*Resolver) ResolveBySSHKey ¶ added in v14.50.0
ResolveBySSHKey resolves a cell address from an SSH key identifier. The key is an opaque string used as the Topology Service SSHKeyClaim. Callers are responsible for choosing a value that the Topology Service recognizes; common values are:
- the raw "key" string passed by sshd to /authorized_keys (base64 body), and
- the SHA256 fingerprint of a signing CA (without the "SHA256:" prefix) for /authorized_certs.
The Topology Service is the source of truth for how these claims are matched.
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.
Source Files
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. |