route

package
v0.1.3 Latest Latest
Warning

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

Go to latest
Published: Jun 13, 2026 License: Apache-2.0 Imports: 4 Imported by: 0

Documentation

Overview

Package route holds the Githome web front's URL-space rules: the reserved top-level names that a user or organization login may not take, and the ref-versus-path split that the tree and blob URLs need. These are pure functions with no dependency on the router or the domain, so the route fidelity oracle tests them directly. See implementation/02 and implementation/07.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AccountSettings

func AccountSettings() string

AccountSettings is the account settings root, /settings. It redirects to the first backed section so a bookmark of the bare root keeps working.

func Appearance

func Appearance() string

Appearance is the account appearance preference, /settings/appearance, where a viewer picks their color mode and the light and dark themes. It is the one account section Githome backs, since the preference rides cookies the color-mode middleware already reads.

func ArchiveTarGz added in v0.1.3

func ArchiveTarGz(owner, name, ref string) string

ArchiveTarGz is the tarball download, /{owner}/{repo}/archive/{ref}.tar.gz.

func ArchiveZip added in v0.1.3

func ArchiveZip(owner, name, ref string) string

ArchiveZip is the zipball download, /{owner}/{repo}/archive/{ref}.zip. The ref may carry slashes; its segments are escaped like every other ref URL so the archive handler's suffix split sees the same boundaries.

func Blame added in v0.1.3

func Blame(owner, name, ref, path string) string

Blame is the line-by-line blame view, /{owner}/{repo}/blame/{ref}/{path}.

func Blob

func Blob(owner, name, ref, path string) string

Blob is a file at a ref, /{owner}/{repo}/blob/{ref}/{path}.

func Branches

func Branches(owner, name string) string

Branches is the branch overview, /{owner}/{repo}/branches.

func CanonicalRepoPath added in v0.1.3

func CanonicalRepoPath(escapedPath, rawQuery, reqOwner, reqRepo, owner, name string) (string, bool)

CanonicalRepoPath rebuilds a repository URL under its canonical owner and name. The store resolves /{owner}/{repo} case-insensitively, so a request for /Octocat/Hello finds octocat/hello; github.com answers that with a 301 to the canonical casing rather than serving the page at every spelling (spec 02 §5.2). The same rewrite serves the rename redirect (§5.3): the old name resolves to the moved repository and the URL is rebuilt under where it lives now.

escapedPath and rawQuery come straight off the request URL; reqOwner and reqRepo are the decoded path parameters the router matched. Only the first two path segments are replaced: the ref and file path that follow are case-sensitive and pass through untouched, query string included. ok is false when the request already uses the canonical spelling, or when the canonical pair is incomplete; the caller serves the page in place then.

func CanonicalRepoTarget added in v0.1.3

func CanonicalRepoTarget(r *http.Request, reqOwner, reqRepo, owner, name string) (string, bool)

CanonicalRepoTarget is CanonicalRepoPath fed from a request, with the method gate every resolver shares: only GET and HEAD are canonicalized. A POST to a wrong-cased path operates on the repository the resolver already found, and a 301 would make the browser replay it as a GET, dropping the body.

func Checks

func Checks(owner, name, ref string) string

Checks is the commit checks page, /{owner}/{repo}/checks/{ref}. ref is a branch, tag, or sha; its segments are escaped and rejoined with literal slashes so a branch with slashes round-trips through the same ref split the code views use.

func CommentDelete

func CommentDelete(owner, name string, number, commentID int64) string

CommentDelete is the delete POST target for a comment, /{owner}/{repo}/issues/{number}/comments/{id}/delete (a POST, since an HTML form cannot issue DELETE without JavaScript).

func CommentEdit

func CommentEdit(owner, name string, number, commentID int64) string

CommentEdit is the edit POST target for a comment, /{owner}/{repo}/issues/{number}/comments/{id}.

func CommentReactions

func CommentReactions(owner, name string, number, commentID int64) string

CommentReactions is the reaction-toggle POST target for a comment, /{owner}/{repo}/issues/{number}/comments/{id}/reactions.

func Commit added in v0.1.3

func Commit(owner, name, sha string) string

Commit is the single-commit view, /{owner}/{repo}/commit/{sha}.

func Commits

func Commits(owner, name, ref, path string) string

Commits is the history view, /{owner}/{repo}/commits/{ref}/{path}. The path is an optional history filter, so an empty path lists the whole ref history.

func Compare added in v0.1.3

func Compare(owner, name, base, head string) string

Compare is the diff and optional PR-creation form for a specific base...head range, /{owner}/{repo}/compare/{base}...{head}.

func CompareExpanded added in v0.1.3

func CompareExpanded(owner, name, base, head string) string

CompareExpanded is Compare with the PR creation form shown, appending ?expand=1.

func ComparePicker added in v0.1.3

func ComparePicker(owner, name string) string

ComparePicker is the branch-picker page for starting a pull request, /{owner}/{repo}/compare.

func Dashboard added in v0.1.3

func Dashboard() string

Dashboard is the signed-in home, /dashboard. The root renders the same page for a signed-in viewer; this is the explicit alias the route map keeps.

func DashboardIssues added in v0.1.3

func DashboardIssues(rawQuery string) string

DashboardIssues is the global issues dashboard, /issues.

func DashboardPulls added in v0.1.3

func DashboardPulls(rawQuery string) string

DashboardPulls is the global pull-request dashboard, /pulls.

func DiffView added in v0.1.3

func DiffView(base string, split, ignoreWS bool) string

DiffView appends GitHub's diff display parameters to a diff page's own path: ?diff=split when the side-by-side view is current and ?w=1 when whitespace is hidden. Only the non-default axes appear, so a plain unified view stays at the bare path; the two parameters compose so a control can flip one and keep the other. The same helper serves the PR Files tab, the compare page, and the commit page so the three diff surfaces honor the identical query grammar.

func Find

func Find(owner, name, ref string) string

Find is the file finder at a ref, /{owner}/{repo}/find/{ref}.

func FirstSegment

func FirstSegment(p string) (head, rest string)

FirstSegment returns the first path segment of p and the remainder, both without leading or trailing slashes. It is the small helper the top-level dispatcher uses to peel "/{owner}/..." without allocating a full split when only the head matters.

func IsReservedTop

func IsReservedTop(name string) bool

IsReservedTop reports whether name is a reserved first path segment. The check is case-insensitive because logins are compared case-insensitively, so a reserved name cannot be taken by changing case.

func Issue

func Issue(owner, name string, number int64) string

Issue is one issue's detail page, /{owner}/{repo}/issues/{number}.

func IssueComment

func IssueComment(owner, name string, number, commentID int64) string

IssueComment is the permalink to a comment on an issue, /{owner}/{repo}/issues/{number}#issuecomment-{id}. The fragment is what the no-JS comment POST redirects to so a reload lands on the appended comment.

func IssueComments

func IssueComments(owner, name string, number int64) string

IssueComments is the new-comment POST target, /{owner}/{repo}/issues/{number}/comments.

func IssueEdit

func IssueEdit(owner, name string, number int64) string

IssueEdit is the sidebar edit POST target, /{owner}/{repo}/issues/{number}/edit, which replaces the labels, assignees, or milestone through the EditIssue patch.

func IssueReactions

func IssueReactions(owner, name string, number int64) string

IssueReactions is the reaction-toggle POST target for the issue body, /{owner}/{repo}/issues/{number}/reactions. The form carries the reaction content.

func IssueState

func IssueState(owner, name string, number int64) string

IssueState is the close/reopen POST target, /{owner}/{repo}/issues/{number}/state. The form carries the target state and an optional comment body so a viewer can close with a comment in one submit.

func IssueTitle

func IssueTitle(owner, name string, number int64) string

IssueTitle is the edit-title POST target, /{owner}/{repo}/issues/{number}/title.

func Issues

func Issues(owner, name, rawQuery string) string

Issues is the issues index, /{owner}/{repo}/issues. The optional rawQuery is the already-encoded ?q=/?page= filter string; an empty rawQuery yields the bare index URL the default-filter view canonicalizes to.

func IssuesQuery

func IssuesQuery(owner, name, q string) string

IssuesQuery builds the index URL for a literal ?q= filter value, encoding the query string itself so a value with spaces or quotes stays a single q parameter. It is the canonical target the filter tabs and label chips link to.

func Join added in v0.1.3

func Join() string

Join is the sign-up form, /join.

func Labels added in v0.1.3

func Labels(owner, name string) string

Labels is the repository's label list, /{owner}/{repo}/labels.

func Login added in v0.1.3

func Login() string

Login is the sign-in form, /login.

func LoginSession added in v0.1.3

func LoginSession() string

LoginSession is the sign-in POST target, /login/session.

func LoginWithReturn added in v0.1.3

func LoginWithReturn(returnTo string) string

LoginWithReturn is the sign-in form carrying the page to come back to after signing in, /login?return_to={url}. It is the bounce target for the function-private surfaces (settings, notifications) an anonymous request hits. The auth handlers validate return_to before honoring it (same-origin paths only), so the builder only escapes it.

func Logout added in v0.1.3

func Logout() string

Logout is the sign-out form, /logout.

func LogoutSession added in v0.1.3

func LogoutSession() string

LogoutSession is the sign-out POST target, /logout/session.

func Milestone added in v0.1.3

func Milestone(owner, name string, number int64, closed bool) string

Milestone is one milestone's page, /{owner}/{repo}/milestone/{number}, github.com's singular form. closed selects the closed-issues tab.

func Milestones added in v0.1.3

func Milestones(owner, name, state string) string

Milestones is the milestone list, /{owner}/{repo}/milestones. state selects the closed tab; empty or "open" yields the bare URL the default tab uses.

func NewIssue

func NewIssue(owner, name string) string

NewIssue is the blank new-issue form, /{owner}/{repo}/issues/new.

func NewRepo added in v0.1.3

func NewRepo() string

NewRepo is the create-repository form, /new. The name is reserved at the top level (fe/route reserved.go), so it can never be read as an owner login.

func Notifications added in v0.1.3

func Notifications(rawQuery string) string

Notifications is the notifications inbox, /notifications. rawQuery is the already-encoded ?all=/?participating=/?page= string and an empty one yields the bare inbox.

func Profile

func Profile(login string) string

Profile is a user or organization profile, /{owner}. It is the overview tab by default; the repositories tab adds the ?tab= facet through ProfileTab.

func ProfileSettings added in v0.1.3

func ProfileSettings() string

ProfileSettings is the account profile settings page, /settings/profile, where a signed-in viewer can update their display name, bio, location, and the other public profile fields.

func ProfileTab

func ProfileTab(login, tab string) string

ProfileTab is a profile at a named tab, /{owner}?tab={tab}. The overview tab is the bare profile with no query, so passing "overview" (or an empty tab) yields the canonical URL rather than a redundant ?tab=overview.

func Pull

func Pull(owner, name string, number int64) string

Pull is the pull-request Conversation tab, /{owner}/{repo}/pull/{number}, the canonical PR page the four tabs hang off.

func PullChecks added in v0.1.3

func PullChecks(owner, name string, number int64) string

PullChecks is the Checks tab, /{owner}/{repo}/pull/{number}/checks, the check-run list at the pull request's head sha.

func PullComment

func PullComment(owner, name string, number, commentID int64) string

PullComment is the permalink to a comment on a PR's Conversation timeline, /{owner}/{repo}/pull/{number}#issuecomment-{id}. A PR shares the issue number space, so its conversation comments carry the same issuecomment anchor the issues timeline uses; the no-JS comment POST redirects here.

func PullComments

func PullComments(owner, name string, number int64) string

PullComments is the new-comment POST target on the Conversation tab, /{owner}/{repo}/pull/{number}/comments.

func PullCommits

func PullCommits(owner, name string, number int64) string

PullCommits is the Commits tab, /{owner}/{repo}/pull/{number}/commits.

func PullFiles

func PullFiles(owner, name string, number int64) string

PullFiles is the Files-changed tab, /{owner}/{repo}/pull/{number}/files, the code-review surface where the shared diff component renders.

func PullFilesExpand added in v0.1.3

func PullFilesExpand(owner, name string, number int64) string

PullFilesExpand is the hunk-unfold endpoint, /{owner}/{repo}/pull/{number}/files/expand. It returns the context rows the collapsed gap hides; the query (path, sha, the per-side start lines, count, and diff mode) names the slice to fetch. The path is the base, with the request parameters appended by the build layer.

func PullMerge

func PullMerge(owner, name string, number int64) string

PullMerge is the merge POST target, /{owner}/{repo}/pull/{number}/merge. The form carries the merge method, the optional commit title and message, and the expected head SHA for optimistic concurrency.

func PullMergeBox

func PullMergeBox(owner, name string, number int64) string

PullMergeBox is the merge-box poll fragment GET target, /{owner}/{repo}/pull/{number}/partials/merge-box. While the box is computing mergeability the component re-fetches this on a backoff; with JS off it is just the same partial the full page already shows.

func PullReviewComment

func PullReviewComment(owner, name string, number, commentID int64) string

PullReviewComment is the permalink to an inline review comment on the Files tab, /{owner}/{repo}/pull/{number}/files#discussion_r{id}.

func PullReviewComments

func PullReviewComments(owner, name string, number int64) string

PullReviewComments is the new-inline-comment POST target, /{owner}/{repo}/pull/{number}/review-comments. The form carries the anchor (path, side, line) and the head commit id the comment pins to; the domain validates the anchor against that commit's diff.

func PullReviewReply

func PullReviewReply(owner, name string, number, rootID int64) string

PullReviewReply is the reply POST target for an existing thread, /{owner}/{repo}/pull/{number}/review-comments/{root}/replies, where root is the thread's first comment.

func PullReviewSummary

func PullReviewSummary(owner, name string, number, reviewID int64) string

PullReviewSummary is the permalink to a submitted review in the Conversation timeline, /{owner}/{repo}/pull/{number}#pullrequestreview-{id}.

func PullReviewThreadResolve

func PullReviewThreadResolve(owner, name string, number, rootID int64) string

PullReviewThreadResolve is the resolve/unresolve toggle POST target for a thread, /{owner}/{repo}/pull/{number}/review-threads/{root}/resolve. The handler reads the thread's current state and flips it, so the one endpoint resolves and unresolves.

func PullReviews

func PullReviews(owner, name string, number int64) string

PullReviews is the submit-a-review POST target, /{owner}/{repo}/pull/{number}/reviews. The form carries the verdict event (approve, request changes, comment) and an optional body.

func PullState

func PullState(owner, name string, number int64) string

PullState is the close/reopen POST target on the Conversation tab, /{owner}/{repo}/pull/{number}/state. It is the PR's own state toggle rather than the issue's, so closing or reopening a pull request lands back on the PR page, not the issue view of the same number.

func Pulls

func Pulls(owner, name, rawQuery string) string

Pulls is the pull-request index, /{owner}/{repo}/pulls. The optional rawQuery is the already-encoded ?q=/?page= filter string; an empty rawQuery yields the bare index URL the default filter canonicalizes to.

func PullsCreate added in v0.1.3

func PullsCreate(owner, name string) string

PullsCreate is the create-PR POST target, /{owner}/{repo}/pulls.

func PullsQuery

func PullsQuery(owner, name, q string) string

PullsQuery builds the index URL for a literal ?q= filter value, encoding the query string itself so a value with spaces or quotes stays a single q parameter. It is the canonical target the state tabs link to.

func Raw

func Raw(owner, name, ref, path string) string

Raw is the raw bytes of a file at a ref, /{owner}/{repo}/raw/{ref}/{path}.

func Repo

func Repo(owner, name string) string

Repo is the repository home, /{owner}/{repo}.

func RepoHook

func RepoHook(owner, name string, hookID int64) string

RepoHook is one webhook's edit page, /{owner}/{repo}/settings/hooks/{hook}, keyed by its public id.

func RepoHookDelete

func RepoHookDelete(owner, name string, hookID int64) string

RepoHookDelete is the delete-webhook POST target, /{owner}/{repo}/settings/hooks/{hook}/delete. Deleting is a POST, never a GET, so a crawler or a prefetch cannot remove a hook.

func RepoHookDelivery

func RepoHookDelivery(owner, name string, hookID, deliveryID int64) string

RepoHookDelivery is one recorded delivery's detail page, /{owner}/{repo}/settings/hooks/{hook}/deliveries/{delivery}.

func RepoHookNew

func RepoHookNew(owner, name string) string

RepoHookNew is the new-webhook form, /{owner}/{repo}/settings/hooks/new. It is a literal segment registered before the {hook} id route, so "new" is never read as an id.

func RepoHookRedeliver

func RepoHookRedeliver(owner, name string, hookID, deliveryID int64) string

RepoHookRedeliver is the replay-delivery POST target, /{owner}/{repo}/settings/hooks/{hook}/deliveries/{delivery}/redeliver.

func RepoHooks

func RepoHooks(owner, name string) string

RepoHooks is a repository's webhooks list, /{owner}/{repo}/settings/hooks.

func RepoSearch

func RepoSearch(owner, name, rawQuery string) string

RepoSearch is the in-repo results page, /{owner}/{repo}/search. The repo scope is implicit in the path, so the builder injects repo:{owner}/{name} before it runs the query; rawQuery carries only the viewer's own ?q= and the facets.

func RepoSettings

func RepoSettings(owner, name string) string

RepoSettings is a repository's settings root, /{owner}/{repo}/settings. It redirects to the first backed section (the webhooks list).

func RepoSettingsDelete added in v0.1.3

func RepoSettingsDelete(owner, name string) string

RepoSettingsDelete is the delete-repository POST target, /{owner}/{repo}/settings/delete. Deleting is a post the danger zone confirms, never a get a crawler could trip.

func RepoSettingsVisibility added in v0.1.3

func RepoSettingsVisibility(owner, name string) string

RepoSettingsVisibility is the change-visibility POST target, /{owner}/{repo}/settings/visibility. Toggling between public and private is a post, never a get, so it sits behind the CSRF guard.

func ReservedTopNames

func ReservedTopNames() []string

ReservedTopNames returns the reserved names in no guaranteed order, for tests and for an admin tool that validates a requested login.

func Search(rawQuery string) string

Search is the global results page, /search. rawQuery is the already-encoded ?q=/?type=/?sort= string; an empty rawQuery yields the bare search landing.

func SettingsApplications added in v0.1.3

func SettingsApplications() string

SettingsApplications is the authorized applications page, /settings/applications.

func SettingsDevelopers added in v0.1.3

func SettingsDevelopers() string

SettingsDevelopers is the developer settings landing, /settings/developers.

func SettingsEmails added in v0.1.3

func SettingsEmails() string

SettingsEmails is the email-addresses page, /settings/emails.

func SettingsKeys added in v0.1.3

func SettingsKeys() string

SettingsKeys is the SSH and GPG keys page, /settings/keys. Githome shows a stub today since the key store is not yet backed; the route is registered so the nav link is live and the honest-absence message is visible.

func SettingsNotifications added in v0.1.3

func SettingsNotifications() string

SettingsNotifications is the notification preferences page, /settings/notifications (distinct from the /notifications inbox).

func SettingsOrganizations added in v0.1.3

func SettingsOrganizations() string

SettingsOrganizations is the organization membership page, /settings/organizations.

func SettingsSecurity added in v0.1.3

func SettingsSecurity() string

SettingsSecurity is the password and authentication page, /settings/security.

func SettingsTokenDelete added in v0.1.3

func SettingsTokenDelete(id int64) string

SettingsTokenDelete is the delete-token POST target, /settings/tokens/{id}/delete. Deleting is a POST, never a GET, so a crawler or a prefetch cannot revoke a credential.

func SettingsTokenNew added in v0.1.3

func SettingsTokenNew() string

SettingsTokenNew is the mint-a-token form, /settings/tokens/new, the dedicated page github.com shows for creating a classic token. It is a literal segment registered before the {id}/delete route, so "new" is never read as a token id.

func SettingsTokens added in v0.1.3

func SettingsTokens() string

SettingsTokens is the personal access tokens page, /settings/tokens: the list of the viewer's classic tokens and the form that mints a new one.

func SplitPatchSuffix added in v0.1.3

func SplitPatchSuffix(s string) (rest, format string, ok bool)

SplitPatchSuffix peels the .diff or .patch suffix off a path tail: the commit, compare, and pull URLs all grow a plain-text twin by suffix (github.com's /commit/{sha}.diff family). ok is false when the tail carries neither suffix, or nothing but the suffix; rest is then the input unchanged so the caller falls through to the HTML page.

func Tags

func Tags(owner, name string) string

Tags is the tag overview, /{owner}/{repo}/tags.

func Tree

func Tree(owner, name, ref, path string) string

Tree is a directory at a ref, /{owner}/{repo}/tree/{ref}/{path}. An empty path addresses the ref root. The ref and each path segment are escaped, but the slashes between them stay literal so the longest-ref split (SplitRefPath) sees the same boundaries the builder wrote.

Types

type CompareSide added in v0.1.3

type CompareSide struct {
	Owner string
	Repo  string
	Ref   string
}

CompareSide is one side of a compare range. Owner and Repo are the optional qualifiers of the owner:ref and owner:repo:ref forms; both empty means the ref lives in the repository the URL names.

type CompareSpec added in v0.1.3

type CompareSpec struct {
	Base   CompareSide
	Head   CompareSide
	TwoDot bool
}

CompareSpec is a parsed compare range. TwoDot marks the "base..head" form, the direct diff between the two ends; the canonical "base...head" form diffs head against the merge base.

func ParseBaseHead added in v0.1.3

func ParseBaseHead(s string) (CompareSpec, bool)

ParseBaseHead parses the basehead parameter of a compare URL. The canonical form is "base...head"; "base..head" selects the two-dot direct diff. Each side is a ref, an owner-qualified "owner:ref", or a fully qualified "owner:repo:ref" (github.com's cross-fork grammar). With no separator the whole string is the head with an empty base, so the caller can substitute the repository's default branch. ok is false when the string cannot parse: an empty side, or a side with more than two colons.

type RefKind

type RefKind int

RefKind names which code-browsing view a URL addresses. The ref picker keeps a viewer on the same kind when they switch refs (a tree stays a tree, a blob stays a blob), so the kind travels with the resolved ref. See implementation/07 section 10.3.

const (
	// KindTree is a directory listing under /tree.
	KindTree RefKind = iota
	// KindBlob is a single file under /blob.
	KindBlob
	// KindCommits is the history view under /commits.
	KindCommits
	// KindRaw is the raw byte view under /raw.
	KindRaw
)

type RefLookup added in v0.1.3

type RefLookup interface {
	Branch(name string) bool
	Tag(name string) bool
	Commitish(rev string) bool
}

RefLookup answers whether a candidate names a branch, a tag, or another commit-ish in the repository. The caller backs it with the repository's ref set so the split stays free of per-candidate git reads.

type RefMatch added in v0.1.3

type RefMatch int

RefMatch classifies what the leading segments of a ref-path tail resolved to. The caller uses it to build the unambiguous revision for the git layer: a bare name is ambiguous down there too, and git's own rev-parse order prefers the tag when a name is both a branch and a tag, while the web routes promise the branch (GitHub's documented precedence). Qualifying the revision from the match kind pins that choice.

const (
	// RefNone marks a tail whose leading segments name nothing.
	RefNone RefMatch = iota
	// RefBranch marks a branch name (refs/heads/...).
	RefBranch
	// RefTag marks a tag name (refs/tags/...).
	RefTag
	// RefCommit marks a commit-ish that is neither: a full or abbreviated
	// object id, or the symbolic HEAD.
	RefCommit
)

func SplitRefPath

func SplitRefPath(tail string, refs RefLookup) (ref string, kind RefMatch, path string, ok bool)

SplitRefPath separates a "<ref>/<path>" tail into its git ref and the file path within that ref. A ref can contain slashes (a branch named release/1.0), so the tail is ambiguous on its own: "main/cmd/foo" could be ref "main" path "cmd/foo", or a branch "main/cmd" path "foo". Git resolves this by preferring the longest leading segment sequence that names an existing ref, so the split tries the whole tail first and peels one trailing segment at a time into the path.

A fully qualified tail (refs/heads/<branch>/... or refs/tags/<tag>/...) names its kind explicitly and resolves to the short name, so the page links it builds are the short form. When a name is both a branch and a tag, the branch wins (kind precedence within each candidate length: branch, then tag, then commit-ish). ok is false when no leading sequence names a ref, which the handler renders as a 404. See implementation/07 section 4.

Jump to

Keyboard shortcuts

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