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
- type BranchDiffResponse
- type BranchResponse
- type CIResponse
- type CheckDetailResponse
- type CommitResponse
- type ConfigResponse
- type OnboardRepoRequest
- type PRResponse
- type RemoteStatus
- type RepoResponse
- type RepoSummary
- type ReposListResponse
- type StackDetail
- type StackSummary
- type TrunkCommitResponse
- type ViewResponse
Constants ¶
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 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(eng engine.BranchReader, branch engine.Branch, node *engine.StackNode, checks *github.CheckStatus) 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"`
}
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 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(eng engine.BranchReader, graph *engine.StackGraph, rootBranch string, allBranches []string, prCount int, scope string, checksMap map[string]*github.CheckStatus) StackDetail
MapStackDetail creates a full StackDetail with all branch info.
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(eng engine.BranchReader, graph *engine.StackGraph, rootBranch string, allBranches []string, prCount int, scope string, owner string) StackSummary
MapStackSummary creates a StackSummary from stack discovery info.
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[int]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.
Source Files