reservation

type ExtendRequest struct {
	// RepoDir is the working tree of the GitOps repo to scan. Extend commits
	// and pushes to it directly, exactly as Reap does: no clone.
	RepoDir string
	// PullRequest is the key the scan matches on, e.g.
	// "giantswarm/hello-world#123".
	PullRequest string
	// User becomes the holder of each reservation Extend renews, and attributes
	// the commits. It need not be the original holder: extend hands it over.
	User string
	// Now is the new start of every reservation Extend resets. Zero means
	// time.Now().
	Now time.Time
	// DryRun commits each extension on local main and pushes nothing.
	DryRun bool
}

type Extended struct {
	// Cluster is the management cluster the reservation lives on.
	Cluster string `json:"cluster"`
	// App is the reservation's chart.
	App string `json:"app"`
	// From and Until bound the new window, in UTC.
	From  time.Time `json:"from"`
	Until time.Time `json:"until"`
}

type HeadBranchFunc func(ctx context.Context, pullRequest string) (string, error)

type ListRequest struct {
	// RepoDir is the working tree of the GitOps repo holding Cluster.
	RepoDir string
	// Cluster is the management cluster name, e.g. "graveler".
	Cluster string
}

type ReapRequest struct {
	// RepoDir is the working tree of the GitOps repo to sweep. Reap commits and
	// pushes to it directly, exactly as Release does: no clone.
	RepoDir string
	// User attributes each release commit Reap makes, e.g. "reservation-reaper".
	// It need not be the original holder, exactly like ReleaseRequest.User.
	User string
	// Now is the clock Reap checks expiry against. Zero means time.Now().
	Now time.Time
	// HeadBranch resolves a reservation's pull request to its current head
	// branch. Required only when some active reservation names one; Reap never
	// calls it for a reservation its expiry already condemns.
	HeadBranch HeadBranchFunc
	// DryRun commits each release on local main and pushes nothing.
	DryRun bool
}

type Reaped struct {
	// Cluster is the management cluster the reservation was released on.
	Cluster string `json:"cluster"`
	// App is the chart Release resolved the reservation to.
	App string `json:"app"`
	// User is the GitHub login of the reservation's original holder -- not
	// ReapRequest.User, which only attributes the release commit.
	User string `json:"user"`
	// Branch is the reservation's stored branch: the one that makes no more
	// builds when Reason is "renamed".
	Branch string `json:"branch"`
	// PullRequest is the reservation's pull request, e.g.
	// "giantswarm/hello-world#123", or empty when it named none.
	PullRequest string `json:"pullRequest,omitempty"`
	// Reason is why Reap released it: ReasonExpired or ReasonRenamed.
	Reason string `json:"reason"`
	// Until is the reservation's expiry, in UTC.
	Until time.Time `json:"until"`
	// Commit is the hash of the commit Release made.
	Commit string `json:"commit"`
}

type ReleaseAllRequest struct {
	// RepoDir is the working tree of the GitOps repo to scan. ReleaseAll
	// commits and pushes to it directly, exactly as Reap and Extend do: no
	// clone.
	RepoDir string
	// PullRequest is the key the scan matches on, e.g.
	// "giantswarm/hello-world#123".
	PullRequest string
	// User attributes each release commit. It need not be the original holder,
	// exactly like ReapRequest.User.
	User string
	// DryRun commits each release on local main and pushes nothing.
	DryRun bool
}

type ReleaseRequest struct {
	// RepoDir is the working tree of the GitOps repo holding Cluster.
	RepoDir string
	// Cluster is the management cluster name, e.g. "graveler".
	Cluster string
	// App names the chart to release. Empty means the chart the app repository
	// at AppDir builds. Release() keys the reservation on the resolved chart,
	// exactly as Reserve does, so this can be Result.App from the original
	// Reserve call.
	App string
	// AppDir is a working tree of the app repository, read only to take the
	// chart name from helm/*/Chart.yaml. It is unused when App is set.
	AppDir string
	// User is the GitHub login of whoever releases the reservation. It need not
	// be the original holder: a colleague or an on-call engineer can release for
	// someone else.
	User string
	// PullRequest, when set, restricts the release to a reservation that pull
	// request holds, e.g. "giantswarm/hello-world#123". Any other pull
	// request's reservation is refused, so releasing from another pull request cannot free a
	// cluster somebody else is testing on. Empty means no check: that is the
	// force-release a human runs from a laptop to clear a stuck lock, and it
	// is what Reap uses.
	PullRequest string
	// DryRun is read only by the sweeps that push: Release itself never
	// pushes.
	DryRun bool
}

type ReleaseResult struct {
	// App is the chart Release resolved the request to.
	App string `json:"app"`
	// Commit is the hash of the commit Release made.
	Commit string `json:"commit"`
	// Files are the repo-relative paths Release removed or edited, sorted.
	Files []string `json:"files,omitempty"`
}

type Released struct {
	// Cluster is the management cluster the reservation lived on.
	Cluster string `json:"cluster"`
	// App is the chart Release resolved the reservation to.
	App string `json:"app"`
	// User is the GitHub login of the reservation's original holder -- not
	// ReleaseAllRequest.User, which only attributes the release commit.
	User string `json:"user"`
	// Branch is the reservation's stored branch.
	Branch string `json:"branch"`
	// Commit is the hash of the commit Release made.
	Commit string `json:"commit"`
}

type Request struct {
	// RepoDir is the working tree of the GitOps repo holding Cluster.
	RepoDir string
	// Cluster is the management cluster name, e.g. "graveler".
	Cluster string
	// App names the collection app to point at the dev builds. Empty means the
	// chart the app repository at AppDir builds. It is required when that
	// repository holds several charts, and it overrides the chart name when a
	// chart is named differently from the chart its URL serves.
	App string
	// AppDir is a working tree of the app repository, read only to take the
	// chart name from helm/*/Chart.yaml. It is unused when App is set.
	AppDir string
	// Branch is the app repo branch whose dev builds the cluster follows.
	Branch string
	// User is the GitHub login of the holder.
	User string
	// PullRequest is the holder's pull request, e.g. "giantswarm/app#123".
	PullRequest string
	// Now is the start of the reservation. Zero means time.Now().
	Now time.Time
	// Duration is how long the reservation lasts. Zero means DefaultDuration, or
	// the cluster's maximum when that is lower.
	Duration time.Duration
	// Scope is the reservation's lock: ScopeApp locks only App, ScopeExclusive
	// locks the whole cluster. Empty means ScopeApp.
	Scope string
}

type Reservation struct {
	// App is the chart the reservation moved. It is the ConfigMap entry's key.
	App string `json:"app"`
	// User is the GitHub login of the holder.
	User string `json:"user"`
	// Branch is the app repo branch the reservation follows.
	Branch string `json:"branch"`
	// PullRequest is the holder's pull request.
	PullRequest string `json:"pullRequest,omitempty"`
	// Scope is the reservation's scope, e.g. ScopeApp.
	Scope string `json:"scope"`
	// From and Until bound the reservation, in UTC. Until is the expiry.
	From  time.Time `json:"from"`
	Until time.Time `json:"until"`
}

type Result struct {
	// App is the chart Reserve resolved the request to. It is the reservation's
	// key on the cluster.
	App string `json:"app"`
	// Commit is the hash of the commit Reserve made.
	Commit string `json:"commit"`
	// SourceName is the name of the new OCIRepository.
	SourceName string `json:"sourceName"`
	// SemverFilter is the version selector the new OCIRepository carries.
	SemverFilter string `json:"semverFilter"`
	// Files are the repo-relative paths Reserve wrote, sorted.
	Files []string `json:"files,omitempty"`
	// From and Until bound the reservation, in UTC.
	From  time.Time `json:"from"`
	Until time.Time `json:"until"`
}