release.proto RawHistoryFolder
1// SPDX-License-Identifier: MIT
2
3syntax = "proto3";
4
5package ermite;
6
7import "google/protobuf/field_mask.proto";
8import "google/protobuf/timestamp.proto";
9
10// Release describes a tag and its notes. Drafts are visible only to writers.
11message Release {
12 int64 id = 1;
13 string repo = 2;
14 string tag = 3;
15 string title = 4;
16 string notes = 5;
17 bool draft = 6;
18 bool prerelease = 7;
19 // Latest identifies the release returned by the latest selector, computed or pinned.
20 bool latest = 8;
21 // TargetCommitish is the tag's commit; empty for a draft without a tag.
22 string target_commitish = 9;
23 // Author is the label of the principal that created the release.
24 string author = 10;
25 google.protobuf.Timestamp created_at = 11;
26 // PublishedAt is unset while draft.
27 google.protobuf.Timestamp published_at = 12;
28 google.protobuf.Timestamp updated_at = 13;
29 // Assets contains uploaded assets only, ordered by name.
30 repeated ReleaseAsset assets = 14;
31}
32
33// ReleaseAsset describes an uploaded file, with a sha256:<hex> digest.
34message ReleaseAsset {
35 int64 id = 1;
36 int64 release_id = 2;
37 // Name is unique within the release, 1–255 characters, without slashes or controls.
38 string name = 3;
39 string label = 4;
40 // ContentType defaults to application/octet-stream.
41 string content_type = 5;
42 int64 size = 6;
43 string digest = 7;
44 string uploader = 8;
45 google.protobuf.Timestamp created_at = 9;
46 google.protobuf.Timestamp updated_at = 10;
47}
48
49// ReleaseService manages releases and their assets. Servers list "releases" in
50// GetVersionResponse.features; other servers answer unimplemented.
51// Published releases follow repository read access; drafts require write access.
52// Unknown or unreadable repositories, releases and assets give not_found.
53// Writes require release:write or a job token with contents: write for the repo;
54// readers and branch-limited tokens receive permission_denied.
55// Invalid names, media types or masks give invalid_argument. Size, asset count
56// and repository quota limits give resource_exhausted and leave no stored upload.
57service ReleaseService {
58 // CreateRelease creates one release per tag (already_exists on duplication).
59 // Publishing without an existing tag is failed_precondition, unless
60 // target_commitish is supplied to create it; existing tags never move.
61 rpc CreateRelease(CreateReleaseRequest) returns (CreateReleaseResponse);
62 // GetRelease selects by id, tag or latest (latest must be true).
63 rpc GetRelease(GetReleaseRequest) returns (GetReleaseResponse);
64 // ListReleases lists newest first, including drafts only for writers.
65 rpc ListReleases(ListReleasesRequest) returns (ListReleasesResponse);
66 // UpdateRelease changes masked fields. Publishing requires an existing tag
67 // or target_commitish to create it; otherwise failed_precondition.
68 rpc UpdateRelease(UpdateReleaseRequest) returns (UpdateReleaseResponse);
69 // DeleteRelease removes a release and its assets.
70 rpc DeleteRelease(DeleteReleaseRequest) returns (DeleteReleaseResponse);
71 // UploadReleaseAsset reserves size before reading. The first message carries
72 // metadata; subsequent messages carry only data, at most 1 MiB per message.
73 // Size must be nonnegative (-1 is refused). An interrupted stream stores no
74 // asset. A taken name gives already_exists unless replace is true. Uploading
75 // to a release of another repo gives failed_precondition.
76 rpc UploadReleaseAsset(stream UploadReleaseAssetRequest) returns (UploadReleaseAssetResponse);
77 // UpdateReleaseAsset changes masked name and label; a taken name gives already_exists.
78 rpc UpdateReleaseAsset(UpdateReleaseAssetRequest) returns (UpdateReleaseAssetResponse);
79 // DeleteReleaseAsset removes an asset.
80 rpc DeleteReleaseAsset(DeleteReleaseAssetRequest) returns (DeleteReleaseAssetResponse);
81 // DownloadReleaseAsset sends asset metadata first, then chunks of at most
82 // 1 MiB. Resume with the offset after the last byte received. An offset
83 // beyond the size gives out_of_range.
84 rpc DownloadReleaseAsset(DownloadReleaseAssetRequest) returns (stream DownloadReleaseAssetResponse);
85 // ListReleaseAssets lists uploaded assets, ordered by name.
86 rpc ListReleaseAssets(ListReleaseAssetsRequest) returns (ListReleaseAssetsResponse);
87 // GetReleaseUsage returns usage (including reserved uploads) and limits.
88 rpc GetReleaseUsage(GetReleaseUsageRequest) returns (GetReleaseUsageResponse);
89}
90
91// CreateReleaseRequest is the request of ReleaseService.CreateRelease.
92message CreateReleaseRequest {
93 string repo = 1;
94 string tag = 2;
95 string target_commitish = 3;
96 string title = 4;
97 string notes = 5;
98 bool draft = 6;
99 bool prerelease = 7;
100 // MakeLatest pins this published non-prerelease as latest. False does not pin the release.
101 bool make_latest = 8;
102}
103
104// CreateReleaseResponse is the response of ReleaseService.CreateRelease.
105message CreateReleaseResponse {
106 Release release = 1;
107}
108
109// ListReleasesRequest is the request of ReleaseService.ListReleases.
110message ListReleasesRequest {
111 string repo = 1;
112 // PageSize is the maximum count; zero uses the server default.
113 int32 page_size = 2;
114 // PageToken is next_page_token from the preceding page, or empty initially.
115 string page_token = 3;
116}
117
118// ListReleasesResponse is the response of ReleaseService.ListReleases.
119message ListReleasesResponse {
120 repeated Release releases = 1;
121 string next_page_token = 2;
122}
123
124// UpdateReleaseRequest is the request of ReleaseService.UpdateRelease.
125message UpdateReleaseRequest {
126 string repo = 1;
127 int64 id = 2;
128 string tag = 3;
129 string target_commitish = 4;
130 string title = 5;
131 string notes = 6;
132 bool draft = 7;
133 bool prerelease = 8;
134 // MakeLatest pins this published non-prerelease as latest. False does not pin the release.
135 bool make_latest = 9;
136 // UpdateMask names the fields to change; unknown paths are invalid_argument.
137 google.protobuf.FieldMask update_mask = 10;
138}
139
140// UpdateReleaseResponse is the response of ReleaseService.UpdateRelease.
141message UpdateReleaseResponse {
142 Release release = 1;
143}
144
145// DeleteReleaseRequest is the request of ReleaseService.DeleteRelease.
146message DeleteReleaseRequest {
147 string repo = 1;
148 int64 id = 2;
149}
150
151// DeleteReleaseResponse is the response of ReleaseService.DeleteRelease.
152message DeleteReleaseResponse {
153}
154
155// UploadReleaseAssetRequest is the request of ReleaseService.UploadReleaseAsset.
156message UploadReleaseAssetRequest {
157 string repo = 1;
158 int64 release_id = 2;
159 string name = 3;
160 string label = 4;
161 string content_type = 5;
162 int64 size = 6;
163 bool replace = 7;
164 bytes data = 8;
165}
166
167// UploadReleaseAssetResponse is the response of ReleaseService.UploadReleaseAsset.
168message UploadReleaseAssetResponse {
169 ReleaseAsset asset = 1;
170}
171
172// UpdateReleaseAssetRequest is the request of ReleaseService.UpdateReleaseAsset.
173message UpdateReleaseAssetRequest {
174 string repo = 1;
175 int64 asset_id = 2;
176 string name = 3;
177 string label = 4;
178 // UpdateMask names the fields to change; unknown paths are invalid_argument.
179 google.protobuf.FieldMask update_mask = 5;
180}
181
182// UpdateReleaseAssetResponse is the response of ReleaseService.UpdateReleaseAsset.
183message UpdateReleaseAssetResponse {
184 ReleaseAsset asset = 1;
185}
186
187// DeleteReleaseAssetRequest is the request of ReleaseService.DeleteReleaseAsset.
188message DeleteReleaseAssetRequest {
189 string repo = 1;
190 int64 asset_id = 2;
191}
192
193// DeleteReleaseAssetResponse is the response of ReleaseService.DeleteReleaseAsset.
194message DeleteReleaseAssetResponse {
195}
196
197// DownloadReleaseAssetResponse is the response of ReleaseService.DownloadReleaseAsset.
198message DownloadReleaseAssetResponse {
199 ReleaseAsset asset = 1;
200 bytes chunk = 2;
201}
202
203// ListReleaseAssetsRequest is the request of ReleaseService.ListReleaseAssets.
204message ListReleaseAssetsRequest {
205 string repo = 1;
206 int64 release_id = 2;
207}
208
209// ListReleaseAssetsResponse is the response of ReleaseService.ListReleaseAssets.
210message ListReleaseAssetsResponse {
211 repeated ReleaseAsset assets = 1;
212}
213
214// GetReleaseUsageRequest is the request of ReleaseService.GetReleaseUsage.
215message GetReleaseUsageRequest {
216 string repo = 1;
217}
218
219// GetReleaseUsageResponse is the response of ReleaseService.GetReleaseUsage.
220message GetReleaseUsageResponse {
221 int64 used_bytes = 1;
222 int64 quota_bytes = 2;
223 int64 asset_max_bytes = 3;
224 int32 assets_max = 4;
225}
226
227// GetReleaseRequest selects exactly one release.
228message GetReleaseRequest {
229 string repo = 1;
230 oneof selector {
231 int64 id = 2;
232 string tag = 3;
233 bool latest = 4;
234 }
235}
236
237// ReleaseAssetTag selects a named asset of a tag.
238message ReleaseAssetTag {
239 string tag = 1;
240 string name = 2;
241}
242
243// ReleaseAssetLatest selects a named asset of the latest release.
244message ReleaseAssetLatest {
245 // Latest must be true.
246 bool latest = 1;
247 string name = 2;
248}
249
250// DownloadReleaseAssetRequest selects an asset and a resume offset.
251message DownloadReleaseAssetRequest {
252 string repo = 1;
253 oneof selector {
254 int64 asset_id = 2;
255 ReleaseAssetTag tag = 3;
256 ReleaseAssetLatest latest = 4;
257 }
258 int64 offset = 5;
259}
260
261// GetReleaseResponse contains the selected release.
262message GetReleaseResponse {
263 Release release = 1;
264}