instance package - github.com/mmedum/gitlab-mcp/v2/internal/instance

Documentation ¶

Overview ¶

Package instance normalizes the GitLab base URL (gitlab.com, or the loopback test instance), checks URLs against it, reads the instance's version and edition, and turns GitLab web URLs into tool arguments.

The base URL is normalized once, so every request and every origin check compares the same scheme, host, port and sub-path (§4.9).

Index ¶

Variables
func IsLoopback(hostname string) bool
type Instance
- func Parse(raw string) (Instance, error)
type Kind
type Metadata
- func NewMetadata(version, revision string, enterprise bool) (Metadata, error)
- func (m Metadata) Edition() string
type Ref
- func (r Ref) RefPathCandidates() []RefPath
type RefPath
type Version
- func ParseVersion(s string) (Version, error)
- func (v Version) String() string

Constants ¶

This section is empty.

Variables ¶

View Source

var ErrInvalid = errors.New("invalid instance or URL")

ErrInvalid is wrapped by every error this package returns. The caller maps it to the [invalid] class.

View Source

var GitLabCom = Instance{/* contains filtered or unexported fields */}

GitLabCom is the one instance this server serves.

Functions ¶

func IsLoopback ¶

func IsLoopback(hostname string) bool

IsLoopback reports whether hostname is localhost or a loopback address (127.0.0.0/8 or ::1). Brackets and a trailing dot are tolerated.

Types ¶

type Instance ¶

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

Instance is a normalized GitLab base URL: scheme, host[:port] and an optional sub-path such as "/gitlab".

func Parse ¶

func Parse(raw string) (Instance, error)

Parse normalizes a base URL. A missing scheme is read as https. http is refused for a host that is not loopback, because the token would travel in the clear.

func (Instance) APIRoot ¶

func (i Instance) APIRoot() *url.URL

APIRoot is WebBase plus /api/v4.

func (Instance) Host ¶

func (i Instance) Host() string

Host is host[:port] as it appears in a URL authority, with an IPv6 address bracketed and the default port left out.

func (Instance) Hostname ¶

func (i Instance) Hostname() string

Hostname is the host without port or brackets.

func (Instance) IsZero ¶

func (i Instance) IsZero() bool

IsZero reports whether i was never parsed.

func (Instance) Path ¶

func (i Instance) Path() string

Path is the sub-path, "" or for example "/gitlab".

func (Instance) ResolveURL ¶

func (i Instance) ResolveURL(raw string) (Ref, error)

ResolveURL turns a GitLab web URL on this instance into tool arguments. A URL on another host is refused, naming the configured instance (§6.1).

func (Instance) SameOrigin ¶

func (i Instance) SameOrigin(u *url.URL) bool

SameOrigin reports whether u has the instance's scheme, host and port. Host case and default ports are normalized.

func (Instance) Scheme ¶

func (i Instance) Scheme() string

Scheme is "https" or "http".

func (Instance) String ¶

func (i Instance) String() string

String is the web root as a URL string.

func (Instance) UnderAPIRoot ¶

func (i Instance) UnderAPIRoot(u *url.URL) bool

UnderAPIRoot reports whether u may carry the token: same origin, no credentials, and a path at or below the API root with no dot segments, raw or percent-encoded. It guards following a Link header (§11).

func (Instance) WebBase ¶

func (i Instance) WebBase() *url.URL

WebBase is the instance's web root. Each call returns a fresh copy, so callers may modify it.

type Kind ¶

type Kind string

Kind is what a resolved web URL points at.

const (
	KindProject      Kind = "project"
	KindIssue        Kind = "issue"
	KindMergeRequest Kind = "merge_request"
	KindFile         Kind = "file"
	KindCommit       Kind = "commit"
	KindCompare      Kind = "compare"
	KindPipeline     Kind = "pipeline"
	KindJob          Kind = "job"
	KindWiki         Kind = "wiki"
)

Kinds resolve_url reports.

type Metadata ¶

type Metadata struct {
	Version    Version
	Revision   string
	Enterprise bool
}

Metadata is what the server keeps from /api/v4/metadata.

func NewMetadata ¶

func NewMetadata(version, revision string, enterprise bool) (Metadata, error)

NewMetadata parses the version metadata reports.

func (Metadata) Edition ¶

func (m Metadata) Edition() string

Edition is "Enterprise" or "Community".

type Ref ¶

type Ref struct {
	Kind    Kind
	Project string // full path, decoded: "example-group/sub/project"
	IID     int64  // issue, merge_request
	ID      int64  // pipeline, job
	SHA     string // commit
	// Ref is the branch, tag or SHA of a file, a tree or a commit
	// listing. See RefPathCandidates for refs with slashes.
	Ref     string
	Path    string // file path, or directory for a tree
	Line    int    // from #L10
	EndLine int    // from #L10-20; 0 for a single line
	From    string // compare
	To      string // compare
	Slug    string // wiki page, may contain slashes
	Note    int64  // from #note_123 on an issue or merge request
	// contains filtered or unexported fields
}

Ref is a web URL turned into tool arguments. Only the fields its Kind uses are set.

func (Ref) RefPathCandidates ¶

func (r Ref) RefPathCandidates() []RefPath

RefPathCandidates lists every split of a blob, raw, tree or commits URL's ref and path, shortest ref first, so a caller can check them against the project's branches and tags with one lookup. It is nil for other kinds.

type RefPath ¶

type RefPath struct{ Ref, Path string }

RefPath is one way to split a URL's ref-and-path.

type Version ¶

type Version struct {
	Major, Minor, Patch int
	// Suffix follows the dash, without it: "pre", "ee", "rc1".
	Suffix string
	// Raw is the text as given, trimmed.
	Raw string
}

Version is a GitLab version as /api/v4/metadata reports it, such as "17.3.1-ee" or "19.5.0-pre".

func ParseVersion ¶

func ParseVersion(s string) (Version, error)

ParseVersion reads "major.minor[.patch][-suffix]". A leading "v" is tolerated and a missing patch reads as 0.

func (Version) String ¶

func (v Version) String() string

String is the canonical form, "17.3.1" or "17.3.1-ee".

Source Files ¶

View all Source files

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