httpcontract

package
v0.21.0 Latest Latest
Warning

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

 Go to latest Published: Jul 10, 2026 License: MIT Imports: 7 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 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, remoteStatus engine.BranchRemoteStatus) BranchResponse

MapBranch converts an engine Branch and its StackNode into an API BranchResponse. remoteStatus should come from a single ReadBranchRemoteStatuses call covering all branches being mapped in the current request, not a per-branch call, since each ReadBranchRemoteStatuses call lists the remote's refs.

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 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 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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.