pagekit

README

pagekit

Go module and HTML templates for sign-in pages, interstitials and other system pages wearing the Giant Swarm brand.

Success, light mode	Error, dark mode

What belongs here

Pages that a service or proxy serves on its own, outside a product UI: the page a browser shows after a sign-in, device-code entry, consent screens, error pages, and later perhaps maintenance or "not found" pages. Application UIs are out of scope.

The design is the source of truth. Each kind of consumer gets it in the form it can take in:

• Go services and CLIs import github.com/giantswarm/pagekit. The design files are embedded in the package, so the pages need no network access at runtime.
• Dex and other consumers that are not Go programs take the same sources as files.

Logos come from giantswarm/brand.

What every page has to meet (responsive, light and dark, accessible, no external requests, …) is listed in docs/requirements.md.

Status

Early. pagekit renders success and error result pages through pagekit.Render. Device-code entry, consent and the files for Dex follow. The survey of existing pages and the plan are tracked in giantswarm/giantswarm#38589.

Usage

pagekit.Render(w, http.StatusBadRequest, pagekit.Page{
	Title:     "Sign-in to GitHub failed",
	Heading:   "Sign-in failed",
	Summary:   "GitHub could not be connected",
	Message:   "The sign-in link expired before it was used. Start the sign-in again from Cursor.",
	Detail:    "state_expired",
	Reference: requestID,
})

A status of 400 or more shows the page as an error. Pass a callback's OAuth error parameter through pagekit.OAuthErrorCode before showing it: it keeps only the error codes the specifications define, since anyone can put text of their choosing into a callback URL. Render sets a Content Security Policy that allows only the page's own inline stylesheet and data: images, so the page loads nothing from the network.

Layout

The module lives at the repository root, and the root directory is the importable package pagekit. Keep it that way:

• Go's //go:embed can only reach files inside the module, so the design sources must sit under the root module.
• The design sources sit in design/: the page template, the stylesheet and the logos.
• The generated CI (architect/go-build), the Makefile and the release tags (vX.Y.Z) all assume a module at the root.

Documentation

Overview

Package pagekit holds the shared design of the standalone pages that Giant Swarm services serve outside a product UI: sign-in results, device-code entry, consent and error pages.

The design sources (page layout, stylesheet, logos and wording) live in this repository next to this package, so the package can embed them and consumers ship the pages inside their own binaries, with nothing loaded at runtime. Consumers that are not Go programs, such as Dex, are meant to take the same sources as files.

Render writes a result page, such as the page a browser shows after a sign-in:

pagekit.Render(w, http.StatusOK, pagekit.Page{
	Title:   "Signed in to GitHub",
	Heading: "Signed in",
	Summary: "GitHub is now connected",
	Message: "You can close this tab and return to Cursor.",
})

Index

• func OAuthErrorCode(code string) string
• func Render(w http.ResponseWriter, status int, p Page)
• type Page

Functions

func OAuthErrorCode

func OAuthErrorCode(code string) string

OAuthErrorCode returns code when it is an error code an authorization response may carry, such as access_denied or login_required, and "" for anything else. Anyone can send a browser to a callback with an error parameter of their choosing, so pass a callback's error through it before showing it, for example as Page.Detail, and log the raw value instead.

The known codes are those the IANA OAuth Extensions Error Registry lists for the authorization endpoint, plus invalid_target, which RFC 8707 registers for the implicit grant's error response.

func Render

func Render(w http.ResponseWriter, status int, p Page)

Render writes p as an HTML response with the given status code. A status of 400 or more shows the page as an error.

Types

type Page

type Page struct {
	// Title is the browser tab title, such as "Signed in to GitHub". It
	// defaults to Heading.
	Title string
	// Heading is the outcome in a few words, such as "Signed in". It
	// defaults to "Done", or "Something went wrong" for an error status.
	Heading string
	// Summary says what the outcome applies to, such as "GitHub is now
	// connected".
	Summary string
	// Message says what to do next, such as "You can close this tab and
	// return to Cursor."
	Message string
	// Detail is a technical hint for support, such as an error code. It is
	// shown in monospace. Pass an OAuth callback's error parameter through
	// OAuthErrorCode first.
	Detail string
	// Reference is a code the person can pass on to support, such as a
	// request ID that also appears in the logs.
	Reference string
}

Page is the content of a result page. All text is escaped, and every field is optional.