1// SPDX-License-Identifier: MIT
2
3// Code generated by protoc-gen-connect-go. DO NOT EDIT.
4//
5// Source: ermite/runner.proto
6
7package ermiteconnect
8
9import (
10 ermite "bnema.dev/ermite-api/gen/ermite"
11 connect "connectrpc.com/connect"
12 context "context"
13 errors "errors"
14 http "net/http"
15 strings "strings"
16)
17
18// This is a compile-time assertion to ensure that this generated file and the connect package are
19// compatible. If you get a compiler error that this constant is not defined, this code was
20// generated with a version of connect newer than the one compiled into your binary. You can fix the
21// problem by either regenerating this code with an older version of connect or updating the connect
22// version compiled into your binary.
23const _ = connect.IsAtLeastVersion1_13_0
24
25const (
26 // RunnerServiceName is the fully-qualified name of the RunnerService service.
27 RunnerServiceName = "ermite.RunnerService"
28)
29
30// These constants are the fully-qualified names of the RPCs defined in this package. They're
31// exposed at runtime as Spec.Procedure and as the final two segments of the HTTP route.
32//
33// Note that these are different from the fully-qualified method names used by
34// google.golang.org/protobuf/reflect/protoreflect. To convert from these constants to
35// reflection-formatted method names, remove the leading slash and convert the remaining slash to a
36// period.
37const (
38 // RunnerServiceRegisterRunnerProcedure is the fully-qualified name of the RunnerService's
39 // RegisterRunner RPC.
40 RunnerServiceRegisterRunnerProcedure = "/ermite.RunnerService/RegisterRunner"
41 // RunnerServiceFetchJobProcedure is the fully-qualified name of the RunnerService's FetchJob RPC.
42 RunnerServiceFetchJobProcedure = "/ermite.RunnerService/FetchJob"
43 // RunnerServiceUpdateJobProcedure is the fully-qualified name of the RunnerService's UpdateJob RPC.
44 RunnerServiceUpdateJobProcedure = "/ermite.RunnerService/UpdateJob"
45 // RunnerServiceAppendLogProcedure is the fully-qualified name of the RunnerService's AppendLog RPC.
46 RunnerServiceAppendLogProcedure = "/ermite.RunnerService/AppendLog"
47 // RunnerServiceHeartbeatProcedure is the fully-qualified name of the RunnerService's Heartbeat RPC.
48 RunnerServiceHeartbeatProcedure = "/ermite.RunnerService/Heartbeat"
49 // RunnerServiceWatchJobProcedure is the fully-qualified name of the RunnerService's WatchJob RPC.
50 RunnerServiceWatchJobProcedure = "/ermite.RunnerService/WatchJob"
51 // RunnerServiceCompleteJobProcedure is the fully-qualified name of the RunnerService's CompleteJob
52 // RPC.
53 RunnerServiceCompleteJobProcedure = "/ermite.RunnerService/CompleteJob"
54)
55
56// RunnerServiceClient is a client for the ermite.RunnerService service.
57type RunnerServiceClient interface {
58 // RegisterRunner registers a runner and returns its runner token, which is
59 // shown only in this response; the runner keeps it. The caller needs the
60 // runner:register scope on a token that is not restricted to repositories
61 // (a runner serves every repository), or the root token. Fails with
62 // unauthenticated without a valid token, permission_denied without the
63 // scope or with a repository-restricted token, invalid_argument if a field
64 // breaks a rule, and already_exists if name is taken by another runner and
65 // replace is not set.
66 RegisterRunner(context.Context, *connect.Request[ermite.RegisterRunnerRequest]) (*connect.Response[ermite.RegisterRunnerResponse], error)
67 // FetchJob asks for a job to run (long poll). The server holds the call
68 // until a queued job matches the runner, or about 50 seconds (never more
69 // than 50) pass, then answers; without a job the response has no job and the
70 // runner calls again after retry_after. Clients set a call timeout above 50
71 // seconds (60 is suggested) and must not poll when they have no free
72 // capacity.
73 //
74 // A job matches when every label of its runs-on is among the labels of the
75 // runner (case-insensitive). A job is given to exactly one runner, even when
76 // many runners and many polls compete; the assignment is recorded before
77 // the response is sent. The job stays QUEUED for the owner until it is
78 // acknowledged.
79 //
80 // Acknowledgement. The runner's first Heartbeat for the job is the
81 // acknowledgement, and the runner sends it as soon as it has the job, before
82 // anything else. If none arrives within 30 seconds of the assignment (the
83 // response was lost, or the runner died), the server cancels the assignment:
84 // the job token is revoked, the job goes back to QUEUED with a fresh token
85 // and can be given to any runner, the same one included; nothing the old
86 // assignment stored is kept. This is not a failure of the job. A job whose
87 // assignment is cancelled 3 times in a row is failed with CI_CONCLUSION_FAILURE
88 // and an error saying so.
89 //
90 // Retry after a lost response. poll_id lets a client retry a poll safely:
91 // a call with the same poll_id as an earlier call of the same runner that
92 // assigned a job returns that same assignment (same Job, same token) as long
93 // as it has not been acknowledged or cancelled, instead of taking another.
94 //
95 // A runner that crashed or whose host restarted cannot resume a job: it does
96 // not keep the job token, so the job fails with the lost-runner error after
97 // the heartbeat timeout (see Heartbeat).
98 //
99 // Needs the runner token. Fails with unauthenticated when the runner was
100 // removed (also ending a call in progress) and invalid_argument if labels
101 // or poll_id break a rule.
102 FetchJob(context.Context, *connect.Request[ermite.FetchJobRequest]) (*connect.Response[ermite.FetchJobResponse], error)
103 // UpdateJob reports the state of the steps of a job while it runs. Needs the
104 // job token. Each call is applied whole or not at all, and repeating an
105 // identical call changes nothing, so a runner may retry after a network
106 // error. To end the job use CompleteJob.
107 //
108 // Fails with invalid_argument if a rule is broken, with failed_precondition
109 // if a step goes back (a COMPLETED step cannot change, a step cannot go from
110 // IN_PROGRESS to PENDING) and with failed_precondition and a JobEnded detail
111 // if the job has ended.
112 UpdateJob(context.Context, *connect.Request[ermite.UpdateJobRequest]) (*connect.Response[ermite.UpdateJobResponse], error)
113 // AppendLog appends lines to the log of a job. Needs the job token.
114 //
115 // The log of a job is one sequence of lines, numbered from 0 across all
116 // steps; offset is the number of lines the server holds when the request is
117 // applied, that is the number of the first line of the request. Calls must
118 // go in order, one at a time, and are idempotent:
119 //
120 // - offset equal to the server's line count: the lines are appended;
121 // - offset below it: the first (count - offset) lines were already stored
122 // (a retry after a lost response) and are skipped, and the rest is
123 // appended; a request entirely stored changes nothing. The skipped lines
124 // are not compared with the stored ones: a retry whose lines differ from
125 // the first attempt is silently dropped, so a client must resend the
126 // same lines at the same offset;
127 // - offset above it: out_of_range (a gap is a bug of the client; the
128 // message gives the line count the server holds).
129 //
130 // The response gives the line count after the call, so a client can check
131 // itself. Offsets resume only after a network error within the same runner
132 // process; they are not a way to resume a job after a crash.
133 //
134 // A request has at most 1,000 lines whose text adds up to at most 64 KiB
135 // (65,536 bytes), all in the same step; more is invalid_argument. A line
136 // longer than that is cut by the client into pieces, see LogLine.continued.
137 //
138 // Steps. The step of a request must be at least the step of the last line
139 // the server holds, because the log is ordered by step (applied lines only:
140 // lines skipped as already stored are not checked); a lower step is
141 // failed_precondition. Lines for a step that UpdateJob has not announced
142 // create it: it starts IN_PROGRESS at the time of its first line, with an
143 // empty name until an UpdateJob gives one.
144 //
145 // The log of a job is limited to 512 MiB (536,870,912 bytes) as stored by
146 // the server (text, timestamps and separators). The call that would exceed
147 // it appends nothing; the server adds a last line saying that the limit was
148 // reached, ends the job with CI_CONCLUSION_FAILURE and RunJob.error set, and
149 // answers failed_precondition with a JobEnded detail like any call after the
150 // end of a job. The runner then stops the job.
151 //
152 // Lines sent after the end of the job are rejected, so a runner flushes all
153 // its AppendLog lines before it calls CompleteJob.
154 //
155 // Fails with invalid_argument if a rule is broken (step number, text with a
156 // line feed or invalid UTF-8, missing time, a continued first line).
157 AppendLog(context.Context, *connect.Request[ermite.AppendLogRequest]) (*connect.Response[ermite.AppendLogResponse], error)
158 // Heartbeat tells the server that the runner is alive and still working on
159 // the job. Needs the job token. The first one acknowledges the assignment
160 // (see FetchJob). The runner then calls it every 30 seconds for as long as
161 // the job runs. The deadline is 2 minutes after the later of the last
162 // heartbeat and the start of the server (so a server restart does not fail
163 // the jobs of runners that could not reach it): past it the server ends the
164 // job with CI_CONCLUSION_FAILURE and the message "The self-hosted runner:
165 // <name> lost communication with the server...". Only Heartbeat counts:
166 // other calls do not keep a job alive.
167 //
168 // A runner that gets unavailable (or any network error) retries Heartbeat
169 // every 5 seconds until it succeeds, instead of waiting for its next 30
170 // second tick, and keeps the job running meanwhile.
171 Heartbeat(context.Context, *connect.Request[ermite.HeartbeatRequest]) (*connect.Response[ermite.HeartbeatResponse], error)
172 // WatchJob streams what the runner must react to. Needs the job token. The
173 // runner opens it when it starts the job and keeps it open; it reopens it
174 // after any error other than unauthenticated and the failed_precondition
175 // that says the job ended, and after a clean close of
176 // the stream that did not end with a JobEnded message.
177 //
178 // When the stream opens and a cancellation has already been requested, the
179 // first message is that request, so a reconnect never misses one. Only the
180 // first reason is sent: a job already cancelled by the owner does not get a
181 // second message when its time budget expires. The server also sends a
182 // Keepalive at least every 30 seconds, which the client ignores. When the
183 // job ends the server sends JobEnded, then closes the stream without error.
184 // On a job that has already ended the call fails like the other RPCs
185 // (failed_precondition with a JobEnded detail).
186 //
187 // On a CancelRequest the runner stops the job as the official runner does
188 // (interrupt, then terminate, then kill) and reports the conclusion given
189 // for the reason with CompleteJob.
190 //
191 // The server does not trust the runner to obey. If no conclusion arrives
192 // within 60 seconds after a cancellation request, whatever the reason (user,
193 // fail-fast, timeout), the server ends the job itself: CI_CONCLUSION_CANCELLED
194 // for user and fail-fast, CI_CONCLUSION_TIMED_OUT for timeout, with an error
195 // saying that the runner did not answer, and the steps not completed are
196 // completed as cancelled. The runner's later CompleteJob returns that result.
197 WatchJob(context.Context, *connect.Request[ermite.WatchJobRequest]) (*connect.ServerStreamForClient[ermite.WatchJobResponse], error)
198 // CompleteJob ends a job: it reports the final steps, the outputs and the
199 // conclusion. Needs the job token, which stays valid for this RPC for 24
200 // hours after the end of the job, however it ended. The call is applied whole
201 // or not at all. Once the job has ended, the token works for no other RPC
202 // (they answer failed_precondition with a JobEnded detail).
203 //
204 // It is idempotent. The first call that finds the job running ends it and
205 // answers applied = true. Any later call, a retry after a lost response or a
206 // call after the server ended the job itself, is not validated and changes
207 // nothing: it answers OK with the stored conclusion and error and
208 // applied = false (a runner whose conclusion differs from the stored one
209 // simply logs it; the outputs it sent are dropped).
210 //
211 // Lines sent with AppendLog after this call are rejected: a runner flushes
212 // all its log lines first. Steps that were not reported COMPLETED when the job
213 // ends are completed by the server as CI_CONCLUSION_CANCELLED (or SKIPPED when
214 // they never started and the job did not end by cancellation).
215 //
216 // Fails with invalid_argument if a rule is broken (including the output
217 // limits) and failed_precondition if a step goes back, as in UpdateJob.
218 CompleteJob(context.Context, *connect.Request[ermite.CompleteJobRequest]) (*connect.Response[ermite.CompleteJobResponse], error)
219}
220
221// NewRunnerServiceClient constructs a client for the ermite.RunnerService service. By default, it
222// uses the Connect protocol with the binary Protobuf Codec, asks for gzipped responses, and sends
223// uncompressed requests. To use the gRPC or gRPC-Web protocols, supply the connect.WithGRPC() or
224// connect.WithGRPCWeb() options.
225//
226// The URL supplied here should be the base URL for the Connect or gRPC server (for example,
227// http://api.acme.com or https://acme.com/grpc).
228func NewRunnerServiceClient(httpClient connect.HTTPClient, baseURL string, opts ...connect.ClientOption) RunnerServiceClient {
229 baseURL = strings.TrimRight(baseURL, "/")
230 runnerServiceMethods := ermite.File_ermite_runner_proto.Services().ByName("RunnerService").Methods()
231 return &runnerServiceClient{
232 registerRunner: connect.NewClient[ermite.RegisterRunnerRequest, ermite.RegisterRunnerResponse](
233 httpClient,
234 baseURL+RunnerServiceRegisterRunnerProcedure,
235 connect.WithSchema(runnerServiceMethods.ByName("RegisterRunner")),
236 connect.WithClientOptions(opts...),
237 ),
238 fetchJob: connect.NewClient[ermite.FetchJobRequest, ermite.FetchJobResponse](
239 httpClient,
240 baseURL+RunnerServiceFetchJobProcedure,
241 connect.WithSchema(runnerServiceMethods.ByName("FetchJob")),
242 connect.WithClientOptions(opts...),
243 ),
244 updateJob: connect.NewClient[ermite.UpdateJobRequest, ermite.UpdateJobResponse](
245 httpClient,
246 baseURL+RunnerServiceUpdateJobProcedure,
247 connect.WithSchema(runnerServiceMethods.ByName("UpdateJob")),
248 connect.WithClientOptions(opts...),
249 ),
250 appendLog: connect.NewClient[ermite.AppendLogRequest, ermite.AppendLogResponse](
251 httpClient,
252 baseURL+RunnerServiceAppendLogProcedure,
253 connect.WithSchema(runnerServiceMethods.ByName("AppendLog")),
254 connect.WithClientOptions(opts...),
255 ),
256 heartbeat: connect.NewClient[ermite.HeartbeatRequest, ermite.HeartbeatResponse](
257 httpClient,
258 baseURL+RunnerServiceHeartbeatProcedure,
259 connect.WithSchema(runnerServiceMethods.ByName("Heartbeat")),
260 connect.WithClientOptions(opts...),
261 ),
262 watchJob: connect.NewClient[ermite.WatchJobRequest, ermite.WatchJobResponse](
263 httpClient,
264 baseURL+RunnerServiceWatchJobProcedure,
265 connect.WithSchema(runnerServiceMethods.ByName("WatchJob")),
266 connect.WithClientOptions(opts...),
267 ),
268 completeJob: connect.NewClient[ermite.CompleteJobRequest, ermite.CompleteJobResponse](
269 httpClient,
270 baseURL+RunnerServiceCompleteJobProcedure,
271 connect.WithSchema(runnerServiceMethods.ByName("CompleteJob")),
272 connect.WithClientOptions(opts...),
273 ),
274 }
275}
276
277// runnerServiceClient implements RunnerServiceClient.
278type runnerServiceClient struct {
279 registerRunner *connect.Client[ermite.RegisterRunnerRequest, ermite.RegisterRunnerResponse]
280 fetchJob *connect.Client[ermite.FetchJobRequest, ermite.FetchJobResponse]
281 updateJob *connect.Client[ermite.UpdateJobRequest, ermite.UpdateJobResponse]
282 appendLog *connect.Client[ermite.AppendLogRequest, ermite.AppendLogResponse]
283 heartbeat *connect.Client[ermite.HeartbeatRequest, ermite.HeartbeatResponse]
284 watchJob *connect.Client[ermite.WatchJobRequest, ermite.WatchJobResponse]
285 completeJob *connect.Client[ermite.CompleteJobRequest, ermite.CompleteJobResponse]
286}
287
288// RegisterRunner calls ermite.RunnerService.RegisterRunner.
289func (c *runnerServiceClient) RegisterRunner(ctx context.Context, req *connect.Request[ermite.RegisterRunnerRequest]) (*connect.Response[ermite.RegisterRunnerResponse], error) {
290 return c.registerRunner.CallUnary(ctx, req)
291}
292
293// FetchJob calls ermite.RunnerService.FetchJob.
294func (c *runnerServiceClient) FetchJob(ctx context.Context, req *connect.Request[ermite.FetchJobRequest]) (*connect.Response[ermite.FetchJobResponse], error) {
295 return c.fetchJob.CallUnary(ctx, req)
296}
297
298// UpdateJob calls ermite.RunnerService.UpdateJob.
299func (c *runnerServiceClient) UpdateJob(ctx context.Context, req *connect.Request[ermite.UpdateJobRequest]) (*connect.Response[ermite.UpdateJobResponse], error) {
300 return c.updateJob.CallUnary(ctx, req)
301}
302
303// AppendLog calls ermite.RunnerService.AppendLog.
304func (c *runnerServiceClient) AppendLog(ctx context.Context, req *connect.Request[ermite.AppendLogRequest]) (*connect.Response[ermite.AppendLogResponse], error) {
305 return c.appendLog.CallUnary(ctx, req)
306}
307
308// Heartbeat calls ermite.RunnerService.Heartbeat.
309func (c *runnerServiceClient) Heartbeat(ctx context.Context, req *connect.Request[ermite.HeartbeatRequest]) (*connect.Response[ermite.HeartbeatResponse], error) {
310 return c.heartbeat.CallUnary(ctx, req)
311}
312
313// WatchJob calls ermite.RunnerService.WatchJob.
314func (c *runnerServiceClient) WatchJob(ctx context.Context, req *connect.Request[ermite.WatchJobRequest]) (*connect.ServerStreamForClient[ermite.WatchJobResponse], error) {
315 return c.watchJob.CallServerStream(ctx, req)
316}
317
318// CompleteJob calls ermite.RunnerService.CompleteJob.
319func (c *runnerServiceClient) CompleteJob(ctx context.Context, req *connect.Request[ermite.CompleteJobRequest]) (*connect.Response[ermite.CompleteJobResponse], error) {
320 return c.completeJob.CallUnary(ctx, req)
321}
322
323// RunnerServiceHandler is an implementation of the ermite.RunnerService service.
324type RunnerServiceHandler interface {
325 // RegisterRunner registers a runner and returns its runner token, which is
326 // shown only in this response; the runner keeps it. The caller needs the
327 // runner:register scope on a token that is not restricted to repositories
328 // (a runner serves every repository), or the root token. Fails with
329 // unauthenticated without a valid token, permission_denied without the
330 // scope or with a repository-restricted token, invalid_argument if a field
331 // breaks a rule, and already_exists if name is taken by another runner and
332 // replace is not set.
333 RegisterRunner(context.Context, *connect.Request[ermite.RegisterRunnerRequest]) (*connect.Response[ermite.RegisterRunnerResponse], error)
334 // FetchJob asks for a job to run (long poll). The server holds the call
335 // until a queued job matches the runner, or about 50 seconds (never more
336 // than 50) pass, then answers; without a job the response has no job and the
337 // runner calls again after retry_after. Clients set a call timeout above 50
338 // seconds (60 is suggested) and must not poll when they have no free
339 // capacity.
340 //
341 // A job matches when every label of its runs-on is among the labels of the
342 // runner (case-insensitive). A job is given to exactly one runner, even when
343 // many runners and many polls compete; the assignment is recorded before
344 // the response is sent. The job stays QUEUED for the owner until it is
345 // acknowledged.
346 //
347 // Acknowledgement. The runner's first Heartbeat for the job is the
348 // acknowledgement, and the runner sends it as soon as it has the job, before
349 // anything else. If none arrives within 30 seconds of the assignment (the
350 // response was lost, or the runner died), the server cancels the assignment:
351 // the job token is revoked, the job goes back to QUEUED with a fresh token
352 // and can be given to any runner, the same one included; nothing the old
353 // assignment stored is kept. This is not a failure of the job. A job whose
354 // assignment is cancelled 3 times in a row is failed with CI_CONCLUSION_FAILURE
355 // and an error saying so.
356 //
357 // Retry after a lost response. poll_id lets a client retry a poll safely:
358 // a call with the same poll_id as an earlier call of the same runner that
359 // assigned a job returns that same assignment (same Job, same token) as long
360 // as it has not been acknowledged or cancelled, instead of taking another.
361 //
362 // A runner that crashed or whose host restarted cannot resume a job: it does
363 // not keep the job token, so the job fails with the lost-runner error after
364 // the heartbeat timeout (see Heartbeat).
365 //
366 // Needs the runner token. Fails with unauthenticated when the runner was
367 // removed (also ending a call in progress) and invalid_argument if labels
368 // or poll_id break a rule.
369 FetchJob(context.Context, *connect.Request[ermite.FetchJobRequest]) (*connect.Response[ermite.FetchJobResponse], error)
370 // UpdateJob reports the state of the steps of a job while it runs. Needs the
371 // job token. Each call is applied whole or not at all, and repeating an
372 // identical call changes nothing, so a runner may retry after a network
373 // error. To end the job use CompleteJob.
374 //
375 // Fails with invalid_argument if a rule is broken, with failed_precondition
376 // if a step goes back (a COMPLETED step cannot change, a step cannot go from
377 // IN_PROGRESS to PENDING) and with failed_precondition and a JobEnded detail
378 // if the job has ended.
379 UpdateJob(context.Context, *connect.Request[ermite.UpdateJobRequest]) (*connect.Response[ermite.UpdateJobResponse], error)
380 // AppendLog appends lines to the log of a job. Needs the job token.
381 //
382 // The log of a job is one sequence of lines, numbered from 0 across all
383 // steps; offset is the number of lines the server holds when the request is
384 // applied, that is the number of the first line of the request. Calls must
385 // go in order, one at a time, and are idempotent:
386 //
387 // - offset equal to the server's line count: the lines are appended;
388 // - offset below it: the first (count - offset) lines were already stored
389 // (a retry after a lost response) and are skipped, and the rest is
390 // appended; a request entirely stored changes nothing. The skipped lines
391 // are not compared with the stored ones: a retry whose lines differ from
392 // the first attempt is silently dropped, so a client must resend the
393 // same lines at the same offset;
394 // - offset above it: out_of_range (a gap is a bug of the client; the
395 // message gives the line count the server holds).
396 //
397 // The response gives the line count after the call, so a client can check
398 // itself. Offsets resume only after a network error within the same runner
399 // process; they are not a way to resume a job after a crash.
400 //
401 // A request has at most 1,000 lines whose text adds up to at most 64 KiB
402 // (65,536 bytes), all in the same step; more is invalid_argument. A line
403 // longer than that is cut by the client into pieces, see LogLine.continued.
404 //
405 // Steps. The step of a request must be at least the step of the last line
406 // the server holds, because the log is ordered by step (applied lines only:
407 // lines skipped as already stored are not checked); a lower step is
408 // failed_precondition. Lines for a step that UpdateJob has not announced
409 // create it: it starts IN_PROGRESS at the time of its first line, with an
410 // empty name until an UpdateJob gives one.
411 //
412 // The log of a job is limited to 512 MiB (536,870,912 bytes) as stored by
413 // the server (text, timestamps and separators). The call that would exceed
414 // it appends nothing; the server adds a last line saying that the limit was
415 // reached, ends the job with CI_CONCLUSION_FAILURE and RunJob.error set, and
416 // answers failed_precondition with a JobEnded detail like any call after the
417 // end of a job. The runner then stops the job.
418 //
419 // Lines sent after the end of the job are rejected, so a runner flushes all
420 // its AppendLog lines before it calls CompleteJob.
421 //
422 // Fails with invalid_argument if a rule is broken (step number, text with a
423 // line feed or invalid UTF-8, missing time, a continued first line).
424 AppendLog(context.Context, *connect.Request[ermite.AppendLogRequest]) (*connect.Response[ermite.AppendLogResponse], error)
425 // Heartbeat tells the server that the runner is alive and still working on
426 // the job. Needs the job token. The first one acknowledges the assignment
427 // (see FetchJob). The runner then calls it every 30 seconds for as long as
428 // the job runs. The deadline is 2 minutes after the later of the last
429 // heartbeat and the start of the server (so a server restart does not fail
430 // the jobs of runners that could not reach it): past it the server ends the
431 // job with CI_CONCLUSION_FAILURE and the message "The self-hosted runner:
432 // <name> lost communication with the server...". Only Heartbeat counts:
433 // other calls do not keep a job alive.
434 //
435 // A runner that gets unavailable (or any network error) retries Heartbeat
436 // every 5 seconds until it succeeds, instead of waiting for its next 30
437 // second tick, and keeps the job running meanwhile.
438 Heartbeat(context.Context, *connect.Request[ermite.HeartbeatRequest]) (*connect.Response[ermite.HeartbeatResponse], error)
439 // WatchJob streams what the runner must react to. Needs the job token. The
440 // runner opens it when it starts the job and keeps it open; it reopens it
441 // after any error other than unauthenticated and the failed_precondition
442 // that says the job ended, and after a clean close of
443 // the stream that did not end with a JobEnded message.
444 //
445 // When the stream opens and a cancellation has already been requested, the
446 // first message is that request, so a reconnect never misses one. Only the
447 // first reason is sent: a job already cancelled by the owner does not get a
448 // second message when its time budget expires. The server also sends a
449 // Keepalive at least every 30 seconds, which the client ignores. When the
450 // job ends the server sends JobEnded, then closes the stream without error.
451 // On a job that has already ended the call fails like the other RPCs
452 // (failed_precondition with a JobEnded detail).
453 //
454 // On a CancelRequest the runner stops the job as the official runner does
455 // (interrupt, then terminate, then kill) and reports the conclusion given
456 // for the reason with CompleteJob.
457 //
458 // The server does not trust the runner to obey. If no conclusion arrives
459 // within 60 seconds after a cancellation request, whatever the reason (user,
460 // fail-fast, timeout), the server ends the job itself: CI_CONCLUSION_CANCELLED
461 // for user and fail-fast, CI_CONCLUSION_TIMED_OUT for timeout, with an error
462 // saying that the runner did not answer, and the steps not completed are
463 // completed as cancelled. The runner's later CompleteJob returns that result.
464 WatchJob(context.Context, *connect.Request[ermite.WatchJobRequest], *connect.ServerStream[ermite.WatchJobResponse]) error
465 // CompleteJob ends a job: it reports the final steps, the outputs and the
466 // conclusion. Needs the job token, which stays valid for this RPC for 24
467 // hours after the end of the job, however it ended. The call is applied whole
468 // or not at all. Once the job has ended, the token works for no other RPC
469 // (they answer failed_precondition with a JobEnded detail).
470 //
471 // It is idempotent. The first call that finds the job running ends it and
472 // answers applied = true. Any later call, a retry after a lost response or a
473 // call after the server ended the job itself, is not validated and changes
474 // nothing: it answers OK with the stored conclusion and error and
475 // applied = false (a runner whose conclusion differs from the stored one
476 // simply logs it; the outputs it sent are dropped).
477 //
478 // Lines sent with AppendLog after this call are rejected: a runner flushes
479 // all its log lines first. Steps that were not reported COMPLETED when the job
480 // ends are completed by the server as CI_CONCLUSION_CANCELLED (or SKIPPED when
481 // they never started and the job did not end by cancellation).
482 //
483 // Fails with invalid_argument if a rule is broken (including the output
484 // limits) and failed_precondition if a step goes back, as in UpdateJob.
485 CompleteJob(context.Context, *connect.Request[ermite.CompleteJobRequest]) (*connect.Response[ermite.CompleteJobResponse], error)
486}
487
488// NewRunnerServiceHandler builds an HTTP handler from the service implementation. It returns the
489// path on which to mount the handler and the handler itself.
490//
491// By default, handlers support the Connect, gRPC, and gRPC-Web protocols with the binary Protobuf
492// and JSON codecs. They also support gzip compression.
493func NewRunnerServiceHandler(svc RunnerServiceHandler, opts ...connect.HandlerOption) (string, http.Handler) {
494 runnerServiceMethods := ermite.File_ermite_runner_proto.Services().ByName("RunnerService").Methods()
495 runnerServiceRegisterRunnerHandler := connect.NewUnaryHandler(
496 RunnerServiceRegisterRunnerProcedure,
497 svc.RegisterRunner,
498 connect.WithSchema(runnerServiceMethods.ByName("RegisterRunner")),
499 connect.WithHandlerOptions(opts...),
500 )
501 runnerServiceFetchJobHandler := connect.NewUnaryHandler(
502 RunnerServiceFetchJobProcedure,
503 svc.FetchJob,
504 connect.WithSchema(runnerServiceMethods.ByName("FetchJob")),
505 connect.WithHandlerOptions(opts...),
506 )
507 runnerServiceUpdateJobHandler := connect.NewUnaryHandler(
508 RunnerServiceUpdateJobProcedure,
509 svc.UpdateJob,
510 connect.WithSchema(runnerServiceMethods.ByName("UpdateJob")),
511 connect.WithHandlerOptions(opts...),
512 )
513 runnerServiceAppendLogHandler := connect.NewUnaryHandler(
514 RunnerServiceAppendLogProcedure,
515 svc.AppendLog,
516 connect.WithSchema(runnerServiceMethods.ByName("AppendLog")),
517 connect.WithHandlerOptions(opts...),
518 )
519 runnerServiceHeartbeatHandler := connect.NewUnaryHandler(
520 RunnerServiceHeartbeatProcedure,
521 svc.Heartbeat,
522 connect.WithSchema(runnerServiceMethods.ByName("Heartbeat")),
523 connect.WithHandlerOptions(opts...),
524 )
525 runnerServiceWatchJobHandler := connect.NewServerStreamHandler(
526 RunnerServiceWatchJobProcedure,
527 svc.WatchJob,
528 connect.WithSchema(runnerServiceMethods.ByName("WatchJob")),
529 connect.WithHandlerOptions(opts...),
530 )
531 runnerServiceCompleteJobHandler := connect.NewUnaryHandler(
532 RunnerServiceCompleteJobProcedure,
533 svc.CompleteJob,
534 connect.WithSchema(runnerServiceMethods.ByName("CompleteJob")),
535 connect.WithHandlerOptions(opts...),
536 )
537 return "/ermite.RunnerService/", http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
538 switch r.URL.Path {
539 case RunnerServiceRegisterRunnerProcedure:
540 runnerServiceRegisterRunnerHandler.ServeHTTP(w, r)
541 case RunnerServiceFetchJobProcedure:
542 runnerServiceFetchJobHandler.ServeHTTP(w, r)
543 case RunnerServiceUpdateJobProcedure:
544 runnerServiceUpdateJobHandler.ServeHTTP(w, r)
545 case RunnerServiceAppendLogProcedure:
546 runnerServiceAppendLogHandler.ServeHTTP(w, r)
547 case RunnerServiceHeartbeatProcedure:
548 runnerServiceHeartbeatHandler.ServeHTTP(w, r)
549 case RunnerServiceWatchJobProcedure:
550 runnerServiceWatchJobHandler.ServeHTTP(w, r)
551 case RunnerServiceCompleteJobProcedure:
552 runnerServiceCompleteJobHandler.ServeHTTP(w, r)
553 default:
554 http.NotFound(w, r)
555 }
556 })
557}
558
559// UnimplementedRunnerServiceHandler returns CodeUnimplemented from all methods.
560type UnimplementedRunnerServiceHandler struct{}
561
562func (UnimplementedRunnerServiceHandler) RegisterRunner(context.Context, *connect.Request[ermite.RegisterRunnerRequest]) (*connect.Response[ermite.RegisterRunnerResponse], error) {
563 return nil, connect.NewError(connect.CodeUnimplemented, errors.New("ermite.RunnerService.RegisterRunner is not implemented"))
564}
565
566func (UnimplementedRunnerServiceHandler) FetchJob(context.Context, *connect.Request[ermite.FetchJobRequest]) (*connect.Response[ermite.FetchJobResponse], error) {
567 return nil, connect.NewError(connect.CodeUnimplemented, errors.New("ermite.RunnerService.FetchJob is not implemented"))
568}
569
570func (UnimplementedRunnerServiceHandler) UpdateJob(context.Context, *connect.Request[ermite.UpdateJobRequest]) (*connect.Response[ermite.UpdateJobResponse], error) {
571 return nil, connect.NewError(connect.CodeUnimplemented, errors.New("ermite.RunnerService.UpdateJob is not implemented"))
572}
573
574func (UnimplementedRunnerServiceHandler) AppendLog(context.Context, *connect.Request[ermite.AppendLogRequest]) (*connect.Response[ermite.AppendLogResponse], error) {
575 return nil, connect.NewError(connect.CodeUnimplemented, errors.New("ermite.RunnerService.AppendLog is not implemented"))
576}
577
578func (UnimplementedRunnerServiceHandler) Heartbeat(context.Context, *connect.Request[ermite.HeartbeatRequest]) (*connect.Response[ermite.HeartbeatResponse], error) {
579 return nil, connect.NewError(connect.CodeUnimplemented, errors.New("ermite.RunnerService.Heartbeat is not implemented"))
580}
581
582func (UnimplementedRunnerServiceHandler) WatchJob(context.Context, *connect.Request[ermite.WatchJobRequest], *connect.ServerStream[ermite.WatchJobResponse]) error {
583 return connect.NewError(connect.CodeUnimplemented, errors.New("ermite.RunnerService.WatchJob is not implemented"))
584}
585
586func (UnimplementedRunnerServiceHandler) CompleteJob(context.Context, *connect.Request[ermite.CompleteJobRequest]) (*connect.Response[ermite.CompleteJobResponse], error) {
587 return nil, connect.NewError(connect.CodeUnimplemented, errors.New("ermite.RunnerService.CompleteJob is not implemented"))
588}