Help us shape the future of Go! Take the 2026 Go Developer Survey

httpcontract

package
v0.30.1 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 9 Imported by: 0

Documentation

Overview

Package httpcontract defines JSON-serializable API response types for stackit HTTP surfaces.

These types form the API contract between the Go server and the frontend. They are intentionally decoupled from engine internals to allow the API to evolve independently.

Index

Constants

View Source
const (
	// TrunkCommitKindRegular is a normal non-stack merge trunk commit.
	TrunkCommitKindRegular = "regular"
	// TrunkCommitKindStackMerge is a stack consolidation merge commit.
	TrunkCommitKindStackMerge = "stack-merge"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BranchDiffResponse

type BranchDiffResponse struct {
	Branch       string `json:"branch"`
	BaseRevision string `json:"baseRevision"`
	HeadRevision string `json:"headRevision"`
	Patch        string `json:"patch"`
}

BranchDiffResponse contains raw patch data for a branch relative to its divergence point.

type BranchInput added in v0.29.0

type BranchInput struct {
	Branch       engine.Branch
	Node         *engine.StackNode
	Checks       *github.CheckStatus
	RemoteStatus engine.BranchRemoteStatus
	Stat         engine.BranchStat
	Commits      git.Commits
	CommitInfo   git.CommitInfo
	NeedsRestack bool
}

BranchInput is everything MapBranch needs about one branch. RemoteStatus, Stat, Commits, CommitInfo, and NeedsRestack should each come from a single batch call covering all branches being mapped in the current request (ReadBranchRemoteStatuses, BatchBranchStats, BatchCommits, BatchCommitInfo, ReadBranchStatuses), not per-branch calls — per-branch reads spawn a git process per field per branch.

func NewBranchInput added in v0.29.0

func NewBranchInput(node *engine.StackNode, checks *github.CheckStatus, data stackview.BranchData) BranchInput

NewBranchInput assembles a BranchInput from the batched data resolved by stackview.FetchBranchData.

type BranchResponse

type BranchResponse struct {
	Name         string           `json:"name"`
	Parent       string           `json:"parent,omitempty"`
	Children     []string         `json:"children,omitempty"`
	Depth        int              `json:"depth"`
	IsCurrent    bool             `json:"isCurrent"`
	NeedsRestack bool             `json:"needsRestack"`
	IsLocked     bool             `json:"isLocked"`
	LockReason   string           `json:"lockReason,omitempty"`
	IsFrozen     bool             `json:"isFrozen"`
	Scope        string           `json:"scope,omitempty"`
	Revision     string           `json:"revision"`
	CommitDate   string           `json:"commitDate"`
	CommitAuthor string           `json:"commitAuthor"`
	CommitCount  int              `json:"commitCount"`
	LinesAdded   int              `json:"linesAdded"`
	LinesDeleted int              `json:"linesDeleted"`
	Commits      []CommitResponse `json:"commits,omitempty"`
	PR           *PRResponse      `json:"pr,omitempty"`
	CI           *CIResponse      `json:"ci,omitempty"`
	RemoteStatus *RemoteStatus    `json:"remoteStatus,omitempty"`
}

BranchResponse contains all information about a single branch.

func MapBranch

func MapBranch(ctx context.Context, eng MapperReader, in BranchInput) BranchResponse

MapBranch converts an engine Branch and its StackNode into an API BranchResponse.

type CIResponse

type CIResponse struct {
	Status         string                `json:"status"` // passing, failing, pending, none
	ReviewDecision string                `json:"reviewDecision"`
	Checks         []CheckDetailResponse `json:"checks,omitempty"`
}

CIResponse contains CI/review status for a branch.

type CheckDetailResponse

type CheckDetailResponse struct {
	Name       string `json:"name"`
	Status     string `json:"status"`
	Conclusion string `json:"conclusion"`
}

CheckDetailResponse contains details about a single CI check.

type CommitResponse

type CommitResponse struct {
	SHA     string `json:"sha"`
	Message string `json:"message"`
	Date    string `json:"date,omitempty"`
}

CommitResponse represents a single commit.

type ConfigResponse added in v0.20.0

type ConfigResponse struct {
	// ReadOnly is true when the server refuses writes (the submit endpoint
	// is disabled). The client hides write affordances.
	ReadOnly bool `json:"readOnly"`
	// AuthRequired is true when reads require a session. It is false on a
	// public read-only server and when auth is disabled, so the client knows
	// not to send the user through a login flow.
	AuthRequired bool `json:"authRequired"`
	// SingleRepo is true when the server runs in single-repo mode (the local
	// `-cwd`/discovery shortcut, not the DB-backed multi-tenant model). The
	// client skips the repo picker and opens the sole repo directly — picking
	// a repo is only meaningful in the hosted, multi-repo model.
	SingleRepo bool `json:"singleRepo"`
}

ConfigResponse advertises server capabilities so the web client can adapt at runtime instead of relying on build-time flags. It is served unauthenticated so the client can learn whether a login is required before attempting one.

type MapperReader added in v0.29.0

type MapperReader interface {
	CurrentBranchName(ctx context.Context) string
	GetScope(branch engine.Branch) engine.Scope
	GetStackDescription(ctx context.Context, branch engine.Branch) *git.StackDescription
}

MapperReader is the engine surface the mappers read beyond their batched inputs.

type OnboardRepoRequest added in v0.20.0

type OnboardRepoRequest struct {
	Owner string `json:"owner,omitempty"`
	Name  string `json:"name,omitempty"`
	URL   string `json:"url,omitempty"`
}

OnboardRepoRequest is the body for POST /api/v1/repos — a request to clone a GitHub repository and start serving it. Provide either Owner+Name or URL; URL is a convenience that is parsed into owner/name. On success the server responds 201 with a RepoSummary for the newly served repo.

type PRResponse

type PRResponse struct {
	Number  int    `json:"number"`
	Title   string `json:"title"`
	State   string `json:"state"` // OPEN, MERGED, CLOSED
	URL     string `json:"url"`
	IsDraft bool   `json:"isDraft"`
	Base    string `json:"base"`
}

PRResponse contains pull request metadata.

type RemoteStatus

type RemoteStatus struct {
	Ahead         bool `json:"ahead"`
	Behind        bool `json:"behind"`
	Diverged      bool `json:"diverged"`
	MissingRemote bool `json:"missingRemote"`
}

RemoteStatus describes how a branch relates to its remote tracking branch.

type RepoResponse

type RepoResponse struct {
	Owner         string `json:"owner"`
	Repo          string `json:"repo"`
	Trunk         string `json:"trunk"`
	CurrentBranch string `json:"currentBranch"`
	Remote        string `json:"remote"`
	CurrentUser   string `json:"currentUser,omitempty"`
}

RepoResponse contains repository metadata.

type RepoSummary added in v0.18.1

type RepoSummary struct {
	ID            string `json:"id"`
	Owner         string `json:"owner,omitempty"`
	Repo          string `json:"repo,omitempty"`
	DisplayName   string `json:"displayName"`
	Trunk         string `json:"trunk"`
	CurrentBranch string `json:"currentBranch,omitempty"`
}

RepoSummary is one entry in ReposListResponse — the metadata clients need to render a repo picker without hitting per-repo endpoints. Owner and Repo are the GitHub coordinates the client uses to build /{owner}/{repo} routes; they are omitted for a repo with no GitHub remote.

type ReposListResponse added in v0.18.1

type ReposListResponse struct {
	Repos []RepoSummary `json:"repos"`
}

ReposListResponse is the response shape for GET /api/v1/repos.

type StackDetail

type StackDetail struct {
	StackSummary
	Branches []BranchResponse `json:"branches"` // DFS order
}

StackDetail is a full stack with all branch details.

func MapStackDetail

func MapStackDetail(ctx context.Context, eng MapperReader, graph *engine.StackGraph, stack StackInput, checksMap github.ChecksByBranch, data stackview.BranchData) StackDetail

MapStackDetail creates a full StackDetail with all branch info. data should come from stackview.FetchBranchData covering every stack being mapped in the current request — see stackview.BranchData.

type StackInput added in v0.29.0

type StackInput struct {
	// RootBranch is the stack's root (a direct child of trunk).
	RootBranch string
	// AllBranches is every branch in the stack, root to tip.
	AllBranches []string
	// PRCount is the number of PRs in the stack.
	PRCount int
	// Scope is the stack's scope, if any.
	Scope engine.Scope
}

StackInput identifies one discovered stack to map.

type StackSummary

type StackSummary struct {
	RootBranch  string `json:"rootBranch"`
	Title       string `json:"title"`
	Status      string `json:"status"` // shippable, pending, blocked, incomplete
	Scope       string `json:"scope,omitempty"`
	BranchCount int    `json:"branchCount"`
	PRCount     int    `json:"prCount"`
	IsCurrent   bool   `json:"isCurrent"`
	HasWorktree bool   `json:"hasWorktree,omitempty"`
	Description string `json:"description,omitempty"`
	Owner       string `json:"owner,omitempty"`
}

StackSummary is a lightweight summary of a stack for list views.

func MapStackSummary

func MapStackSummary(ctx context.Context, eng MapperReader, graph *engine.StackGraph, stack StackInput, owner string, statuses engine.BranchStatuses) StackSummary

MapStackSummary creates a StackSummary from stack discovery info. owner is the stack root's PR author, or "" when unknown. statuses should come from a single ReadBranchStatuses batch call covering every stack being summarized in the current request, not one call per stack — see stackview.BranchData.

type TrunkCommitResponse

type TrunkCommitResponse struct {
	SHA           string         `json:"sha"`
	Message       string         `json:"message"`
	Author        string         `json:"author"`
	Date          string         `json:"date"`
	Kind          string         `json:"kind"`
	PRNumber      int            `json:"prNumber,omitempty"`
	StackSize     int            `json:"stackSize,omitempty"`
	StackPRs      []int          `json:"stackPRs,omitempty"`
	StackPRTitles map[int]string `json:"stackPRTitles,omitempty"`
	StackScope    string         `json:"stackScope,omitempty"`
}

TrunkCommitResponse represents a commit on the trunk branch, optionally enriched with stack metadata from git trailers.

func MapTrunkCommits

func MapTrunkCommits(commits []git.RecentCommit, prTitles map[git.PRNumber]string) []TrunkCommitResponse

MapTrunkCommits converts git RecentCommit values to API TrunkCommitResponse values. Commits whose PR number is already represented by a stack-merge's StackPRs are filtered out so that consolidated stacks don't show duplicate entries. prTitles is an optional map of PR number to title; pass nil if unavailable.

type ViewResponse

type ViewResponse struct {
	Repo           RepoResponse          `json:"repo"`
	Stacks         []StackDetail         `json:"stacks"`
	RecentlyMerged []TrunkCommitResponse `json:"recentlyMerged,omitempty"`
}

ViewResponse is the combined response for the frontend view. It bundles repo metadata and all stack details into a single payload to avoid N+1 API calls.

Jump to

Keyboard shortcuts

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