rest

Documentation

Overview

Package rest implements Githome's REST API v3. It mounts onto a mizu router and is the only place HTTP request handling for the REST surface lives. Handlers call the domain layer for data and the presenter layer for rendering; they never touch the store or git directly.

Index

• func Mount(root *mizu.Router, d Deps)
• type Deps
• type FieldError
• type Page
  • func (p Page) HasNextPage() bool
  • func (p Page) Offset() int
• type Pinger

Functions

func Mount

func Mount(root *mizu.Router, d Deps)

Mount wires the REST routes onto root. The API is served at the GHES-style /api/v3 prefix and, unless the web front owns the root (Deps.WebFront), also at the bare github.com-style root, sharing one set of handlers and the version/media-type middleware. Health probes sit outside that chain, and any unmatched path returns the GitHub-shaped 404 (again, unless the web front owns the root and supplies its own).

Types

type Deps

type Deps struct {
	Config     config.Config
	Logger     *slog.Logger
	Ready      Pinger
	Auth       *auth.Service
	Users      *domain.UserService
	Repos      *domain.RepoService
	Issues     *domain.IssueService
	Pulls      *domain.PRService
	Reviews    *domain.ReviewService
	Checks     *domain.ChecksService
	Hooks      *domain.HookService
	Events     *domain.EventService
	Search     *domain.SearchService
	URLs       *presenter.URLBuilder
	NodeFormat nodeid.Format

	// WebFront reports that the server-rendered web front is mounted on the same
	// router and owns the bare root namespace (/{owner}/{repo}). When set, the
	// dotcom-style root API mount and the root catch-all 404 are omitted: the API
	// answers only under the GHES /api/v3 prefix (GraphQL under /api/graphql),
	// which is the single-host layout GHES itself uses. Without it the API also
	// answers at the bare root, the github.com-style shape, but those wildcard
	// routes cannot coexist with the web front's own /{owner}/{repo} wildcards on
	// one net/http mux: the mux rejects the overlapping patterns at registration.
	WebFront bool
}

Deps are the dependencies the REST surface needs to mount. The auth, domain, and presenter members arrive in M1; a zero member leaves its routes unmounted, which keeps the M0 foundation tests able to build a minimal surface.

type FieldError

type FieldError struct {
	Resource string `json:"resource"`
	Field    string `json:"field"`
	Code     string `json:"code"`
	Message  string `json:"message,omitempty"`
}

FieldError is one entry in a 422 validation error's errors array. Code is one of: missing, missing_field, invalid, already_exists, unprocessable, custom.

type Page

type Page struct {
	Page    int
	PerPage int
	Total   int
	Last    int
	HasPrev bool
	HasNext bool
}

Page is one page of a list response. Page and PerPage come from the request; Total is filled in by the handler from the domain count once the page is fetched, and finalize derives the navigation flags the Link header needs.

func (Page) HasNextPage

func (p Page) HasNextPage() bool

HasNextPage reports whether there is at least one more page after this one, using the Total set by the handler. It is called before finalize so the handler can decide whether to build a cursor before writing the Link header.

func (Page) Offset

func (p Page) Offset() int

Offset is the row offset this page starts at, the value the store query takes.

type Pinger

type Pinger interface {
	Ping(ctx context.Context) error
}

Pinger is the readiness dependency: anything that can verify its backing store is reachable. *store.Store satisfies it.