1// SPDX-License-Identifier: AGPL-3.0-or-later
2
3package ports
4
5import (
6 "time"
7
8 "bnema.dev/ermite/internal/domain"
9)
10
11// The parameters and results of the use case interfaces (services.go). They
12// live here so that the adapters that call the use cases and the use cases
13// themselves share them without importing each other.
14
15// RepoPage is a page of repositories ordered by name.
16type RepoPage struct {
17 Repos []domain.Repo
18 // NextPageToken is empty on the last page.
19 NextPageToken string
20}
21
22// RepoView is a repository with the Git state that belongs in its summary.
23type RepoView struct {
24 domain.Repo
25 // DefaultBranch is the branch HEAD points to, even when it does not exist
26 // yet; empty when HEAD is detached or the directory is missing.
27 DefaultBranch string
28}
29
30// CreateRepoParams are the settings of a new repository.
31type CreateRepoParams struct {
32 Name domain.RepoName
33 Description string
34 // Visibility defaults to private when empty.
35 Visibility domain.Visibility
36}
37
38// UpdateRepoParams are the changes of Update; a nil field is left alone.
39type UpdateRepoParams struct {
40 Description *string
41 Visibility *domain.Visibility
42 DefaultBranch *string
43 // AllowedMergeModes replaces the allowed merge modes; it must hold at
44 // least one known mode.
45 AllowedMergeModes *[]domain.MergeMode
46 // FailingChecksBlock replaces the setting of that name.
47 FailingChecksBlock *bool
48}
49
50// TokenPage is a page of stored tokens, newest first.
51type TokenPage struct {
52 Tokens []domain.Token
53 // NextPageToken is empty on the last page.
54 NextPageToken string
55}
56
57// CreateTokenParams are the settings of a new token.
58type CreateTokenParams struct {
59 Label string
60 // Scopes must not be empty.
61 Scopes []domain.Scope
62 // Repos limits the token to these repositories; empty means every one.
63 Repos []domain.RepoName
64 // BranchPrefixes limits the token to the branches under these prefixes
65 // (see domain.ParseBranchPrefix); empty means every branch.
66 BranchPrefixes []string
67 // ExpiresAt is the zero time for a token that never expires.
68 ExpiresAt time.Time
69}
70
71// CreatedToken is a new token with its secret, which is shown once and never
72// stored.
73type CreatedToken struct {
74 Token domain.Token
75 Secret string
76}
77
78// ListRefsParams selects the refs to list.
79type ListRefsParams struct {
80 // Kinds restricts the result; empty means every kind.
81 Kinds []domain.RefKind
82 // PageSize is 0 for the default, and lowered to MaxRefPageSize.
83 PageSize int
84 // PageToken is the NextPageToken of the previous page, or empty.
85 PageToken string
86}
87
88// RefPage is a page of refs.
89type RefPage struct {
90 Refs []domain.Ref
91 // NextPageToken is empty on the last page.
92 NextPageToken string
93}
94
95// ListCommitsParams selects a page of history.
96type ListCommitsParams struct {
97 // Revision is where the history starts; the zero value is HEAD. Ignored
98 // when PageToken is set: the token pins the commit the first page started
99 // from, so every page walks the same history even if a branch moves.
100 Revision domain.Revision
101 // Path limits the history to the commits that changed it. It must be the
102 // same on every page of a listing.
103 Path domain.TreePath
104 // PageSize is 0 for the default, and lowered to MaxPageSize.
105 PageSize int
106 // PageToken is the NextPageToken of the previous page, or empty.
107 PageToken string
108}
109
110// HistoryPage is a page of history, newest first.
111type HistoryPage struct {
112 Commits []domain.Commit
113 // NextPageToken is empty on the last page.
114 NextPageToken string
115}
116
117// RepoStats are the figures of a repository the home page shows.
118type RepoStats struct {
119 // Commits is the number of commits of the default branch; Recent of them
120 // were committed in the last RecentDays days.
121 Commits, Recent int
122 // LatestTag is the most recently created tag; nil without tags.
123 LatestTag *domain.TagInfo
124}
125
126// RecentDays is the window of RepoStats.Recent.
127const RecentDays = 30
128
129// WatchParams select the events of a watch.
130type WatchParams struct {
131 // Topics are TopicHome or "repo:<name>"; empty means TopicHome.
132 Topics []string
133 // ResumeAfter is the id of the last event the caller saw; empty to
134 // receive only new events.
135 ResumeAfter string
136 // Client identifies where the watch comes from, for the limit per client
137 // (MaxWatchersPerClient): an opaque key such as a normalized address; the
138 // web passes its visitor's. Empty only for callers with no client, which
139 // count against MaxWatchers alone.
140 Client string
141 // Ready, when not nil, is called once the topics are valid and the watch
142 // is registered: events published from then on are not missed. Nothing is
143 // sent before it returns.
144 Ready func()
145}
146
147// WatchEvent is one item of a watch.
148type WatchEvent struct {
149 // ID identifies the event, for resuming. Empty on a gap.
150 ID string
151 // Gap tells that events were lost: the caller must reload what it shows.
152 // Event is nil then.
153 Gap bool
154 // Event is a domain.RepoCreated, RepoUpdated, RepoDeleted, PushEvent,
155 // MergeRequestOpened, MergeRequestMerged, MergeRequestClosed,
156 // MergeRequestReady, CommentAdded, RunUpdated or JobUpdated.
157 Event domain.Event
158 // Repo is the state of the repository at delivery, for RepoCreated and
159 // RepoUpdated.
160 Repo *RepoView
161}
162
163// CreateMergeRequestParams describes the merge request to open.
164type CreateMergeRequestParams struct {
165 Title string
166 Description string
167 // Source is required; Target defaults to the default branch.
168 Source, Target string
169}
170
171// ListMergeRequestsParams selects a page of merge requests.
172type ListMergeRequestsParams struct {
173 // State restricts the result; empty means every state.
174 State domain.MRState
175 // PageSize is 0 for the default, and lowered to MaxPageSize.
176 PageSize int
177 // PageToken is the NextPageToken of the previous page, or empty.
178 PageToken string
179}
180
181// MergeRequestPage is a page of merge requests, highest number first.
182type MergeRequestPage struct {
183 MergeRequests []domain.MergeRequest
184 // NextPageToken is empty on the last page.
185 NextPageToken string
186}
187
188// MergeRequestDetail is a merge request with its review data.
189type MergeRequestDetail struct {
190 MergeRequest domain.MergeRequest
191 // Commits are the commits of the head that the target lacks, newest
192 // first, at most MaxMergeRequestCommits.
193 Commits []domain.Commit
194 CommitsTruncated bool
195 // DiffBaseID is the commit the diff compares from; zero when the source
196 // branch is gone, then the diff is empty.
197 DiffBaseID domain.ObjectID
198 Stats domain.DiffStats
199 Diff domain.Diff
200 // Comments are the comments, oldest first.
201 Comments []domain.Comment
202 // LastReadID is the head recorded by MarkRead; zero when none.
203 LastReadID domain.ObjectID
204 // LastReadLost tells that since-last-read was asked for, a head was
205 // recorded, but that commit is gone: the diff is against the target.
206 LastReadLost bool
207}
208
209// GetMergeRequestOptions say which diff MergeRequestService.Get reads.
210type GetMergeRequestOptions struct {
211 // SinceLastRead compares the head recorded by MarkRead with the head (see Get).
212 SinceLastRead bool
213 // Files, when set, lists every changed file, without the file-count
214 // limit, and reads the hunks of the files in the window only, each within
215 // the per-file and the total limits of domain.DefaultDiffLimits. Unset,
216 // the diff is bounded by domain.DefaultDiffLimits (the API contract).
217 Files *FileWindow
218 // Base and Head, when not zero, are the diff the caller shows: Get
219 // returns domain.ErrConflict when the request's diff base or head differ
220 // (the branch moved, a read was marked).
221 Base, Head domain.ObjectID
222 // DiffOnly skips the commits of the request (Commits stays empty).
223 DiffOnly bool
224}
225
226// FileWindow is the range [From, To) of files whose hunks are read.
227type FileWindow struct{ From, To int }
228
229// AddCommentParams describes the comment to add.
230type AddCommentParams struct {
231 // Path, Line and Side designate a line of the diff; all empty for a
232 // general comment.
233 Path string
234 Line int
235 Side domain.DiffSide
236 Text string
237}
238
239// MergeParams describes the merge to perform.
240type MergeParams struct {
241 // Mode defaults to fast-forward.
242 Mode domain.MergeMode
243 // HeadID is the commit the caller reviewed; the source branch must still
244 // point to it.
245 HeadID domain.ObjectID
246 // DeleteSource deletes the source branch after the merge.
247 DeleteSource bool
248}
249
250// MergeResult is a merged request and what happened to its source branch.
251type MergeResult struct {
252 domain.MergeRequest
253 // SourceDeleted is true when DeleteSource was asked and the branch is
254 // gone.
255 SourceDeleted bool
256}
257
258// LoginLink is a login link as the owner receives it.
259type LoginLink struct {
260 // URL holds the secret: show it once, never log it.
261 URL string
262 ExpiresAt time.Time
263}