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 SSHFingerprintClaim(fingerprint string) *types_proto.Claim
- func SSHKeyClaim(key string) *types_proto.Claimdeprecated
- func UsernameClaim(username string) *types_proto.Claim
- type Client
- type Config
- type Resolver
- func (r *Resolver) ClientForRoute(ctx context.Context, httpClient *client.GitlabNetClient, repoPath string) RoutedClient
- func (r *Resolver) ClientForSSHFingerprint(ctx context.Context, httpClient *client.GitlabNetClient, fingerprint string) RoutedClient
- func (r *Resolver) ClientForSSHKey(ctx context.Context, httpClient *client.GitlabNetClient, key string) RoutedClientdeprecated
- func (r *Resolver) ClientForUserArgs(ctx context.Context, httpClient *client.GitlabNetClient, args UserArgs) RoutedClient
- type RoutedClient
- type TLSConfig
- type UserArgs
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 SSHFingerprintClaim ¶ added in v14.54.0
func SSHFingerprintClaim(fingerprint string) *types_proto.Claim
SSHFingerprintClaim creates a Claim for an SSH key's SHA-256 fingerprint. The fingerprint must be the raw base64 body (43 chars), without the "SHA256:" prefix. This matches the keys.fingerprint_sha256 format stored in the GitLab database.
func SSHKeyClaim
deprecated
added in
v14.50.0
func SSHKeyClaim(key string) *types_proto.Claim
SSHKeyClaim creates a Claim for an SSH public key.
Deprecated: Use SSHFingerprintClaim instead to classify by SHA-256 fingerprint.
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
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) 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) ClientForSSHFingerprint ¶ added in v14.54.0
func (r *Resolver) ClientForSSHFingerprint(ctx context.Context, httpClient *client.GitlabNetClient, fingerprint string) RoutedClient
ClientForSSHFingerprint resolves the cell that owns the SSH key identified by its SHA-256 fingerprint and returns a RoutedClient. The fingerprint must be the raw base64 body (43 chars), without the "SHA256:" prefix. 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
deprecated
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.
Deprecated: Use ClientForSSHFingerprint instead to classify by SHA-256 fingerprint.
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.ClientForSSHFingerprint, 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.
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. |