// SPDX-License-Identifier: MIT

syntax = "proto3";

package ermite;

// ServerService describes the server itself.
service ServerService {
  // GetVersion returns the server version and the optional capabilities of the
  // contract it implements. It needs no authentication, so a client can call
  // it first to check compatibility.
  rpc GetVersion(GetVersionRequest) returns (GetVersionResponse);
  // GetSigningKey returns the public key with which the server signs the
  // commits it creates (squash merges, see MergeMode). It needs no
  // authentication: the key is public, and anyone verifying a commit needs it.
  // Servers that implement it list "signing_key" in
  // GetVersionResponse.features.
  rpc GetSigningKey(GetSigningKeyRequest) returns (GetSigningKeyResponse);
}

// GetVersionRequest is empty.
message GetVersionRequest {}

// GetVersionResponse describes the running server.
message GetVersionResponse {
  // Version is the server release, for example "v0.4.0", or "devel" for an
  // untagged build. Informational: clients must not compare it to decide what
  // is supported, they use features instead.
  string version = 1;
  // Features lists identifiers of the optional capabilities of the contract
  // that this server implements, for example "repo.update" or
  // "events.resume". A client that needs a capability missing from this list
  // should warn instead of failing on an unimplemented RPC or ignored field.
  // Identifiers are lowercase, dot-separated and never reused. The CI
  // identifiers are "ci.runs" (RunService runs, jobs, logs, checks, and the
  // run_updated and job_updated events), "ci.runs.filters" (ListRuns honours
  // its filters) and "ci.runners" (RunnerService, and RunService.ListRunners
  // and RemoveRunner). The CI execution identifiers are "ci.actions"
  // (RunnerService.ResolveActions and Job.github_token), "ci.annotations"
  // (annotations in UpdateJob and CompleteJob, and RunService.ListAnnotations)
  // and "ci.summaries" (RunnerService.UploadSummary and
  // RunService.GetStepSummaries). The CI platform identifiers are "ci.secrets"
  // (SecretService, VariableService and EnvironmentService, and in Job the
  // secrets, vars, environment, permissions and trusted fields and Run.trusted),
  // "ci.dispatch" (RunService.DispatchWorkflow), "ci.concurrency"
  // (CI_STATUS_PENDING and RunJob.concurrency_group) and "ci.cache" (Job.cache).
  repeated string features = 2;
}

// GetSigningKeyRequest is empty.
message GetSigningKeyRequest {}

// GetSigningKeyResponse describes the commit signing key of the server.
message GetSigningKeyResponse {
  // PublicKey is the public key as one OpenSSH authorized_keys line, for
  // example "ssh-ed25519 AAAA...". Commits are signed in the SSH signature
  // format (SSHSIG).
  string public_key = 1;
  // Fingerprint is the SHA-256 fingerprint of the key, in the form
  // "SHA256:<base64>" that ssh-keygen prints.
  string fingerprint = 2;
  // CommitterName is the name the server records as the committer of the
  // commits it creates.
  string committer_name = 3;
  // CommitterEmail is the email address the server records as the committer of
  // the commits it creates. It is the principal of allowed_signers.
  string committer_email = 4;
  // AllowedSigners is a ready-to-use line for an allowed signers file
  // ("<committer_email> <public_key>"), to verify these commits with
  // "git config gpg.ssh.allowedSignersFile".
  string allowed_signers = 5;
}