go.chromium.org/luci@v0.0.0-20240309015107-7cdc2e660f33/server/quota/quotapb/service.proto

// Copyright 2022 The LUCI Authors. All rights reserved.
// Use of this source code is governed under the Apache License, Version 2.0
// that can be found in the LICENSE file.

syntax = "proto3";

import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

import "validate/validate.proto";

import "go.chromium.org/luci/server/quota/quotapb/account.proto";
import "go.chromium.org/luci/server/quota/quotapb/ids.proto";
import "go.chromium.org/luci/server/quota/quotapb/op.proto";
import "go.chromium.org/luci/server/quota/quotapb/policy_config.proto";

option go_package = "go.chromium.org/luci/server/quota/quotapb";

package go.chromium.org.luci.server.quota.quotapb;

// A GetAccountsRequest is a request to fetch multiple Account entries.
//
// You must have the `quota.accounts.read` permission in the realm of all the
// indicated accounts.
message GetAccountsRequest {
  // A list of specific accounts to fetch.
  repeated AccountID account = 1;
}

// GetAccountsResponse is the response to GetAccounts()
message GetAccountsResponse {
  message AccountState {
    AccountID id = 1[
      (validate.rules).message.required = true
    ];

    // The current account, if the account exists, unset otherwise.
    Account account = 2;

    // Contains the effective balance for the account, given its current
    // refill policy and updated_ts.
    int64 projected_balance = 3;
  }
  repeated AccountState accounts = 1;
}

// ApplyOpsRequest allows a number of quota operations to be performed atomically.
message ApplyOpsRequest {
  // If provided, the service will de-duplicate the request based on this ID,
  // namespaced to the calling user.
  //
  // Once this ApplyOpsRequest successfully applies once, futher ApplyOpsRequests
  // within `request_id_ttl` will immediately return as successful.
  string request_id = 1;

  // Must be set, and positive, if request_id is set.
  //
  // If this is omitted, the request_id_ttl is 2 hours.
  //
  // If this is zero, the request_id_ttl is infinite.
  google.protobuf.Duration request_id_ttl = 2 [
    (validate.rules).duration.required = false,
    (validate.rules).duration.gt.seconds = 0
  ];

  // The operations to apply.
  repeated Op ops = 3;
}

// OpResult contains the summary of applying a single Op as part of an
// ApplyOpsRequest.
//
// Note that `previous_balance` and `balance` are first in this message to make
// the success-case encoding of an OpResult with non-zero balances as compact as
// possible (will be represented by a 2-number msgpack array, rather than
// a msgpack object).
message OpResult {
  // This will be set to the balance of the Account after the SUCCESS-ful
  // operation.
  int64 new_balance = 1;

  // If the account already existed, this will be set to the balance observed at
  // the start of this Operation (after applying refill under existing policy,
  // if the account had one set). If the account did not previously exist, this
  // will be 0, even if the Policy in this Op would set a default value.
  //
  // Note that if the same account is used for multiple operations in the same
  // RPC, for the N'th operation on account X, this will have the N-1'th
  // `balance` value.
  int64 previous_balance = 2;

  enum AccountStatus {
    // This Op updated an existing account.
    ALREADY_EXISTS = 0;

    // This Op resulted in the creation of an account.
    CREATED = 1;

    // This Op found an existing, unreadable, account, and the account was
    // recreated (as if it were missing).
    //
    // Note that this is supposed to be a rare condition, and will be monitored
    // on the server side. If seen at elevated rates, this is likely alertable.
    RECREATED = 2;
  }
  AccountStatus account_status = 3;

  enum OpStatus {
    // The Operation was successful.
    SUCCESS = 0;

    // There was an otherwise-unclassified error while applying this operation.
    ERR_UNKNOWN = 1;

    // The Op failed because it would bring the Account balance above the policy
    // limit.
    ERR_OVERFLOW = 2;

    // The Op failed because it would bring the Account balance below 0.
    ERR_UNDERFLOW = 3;

    // The Op failed because it referred to a Policy which doesn't exist.
    ERR_UNKNOWN_POLICY = 4;

    // The Op failed because it applied to a non-existant Account and no Policy
    // was given.
    ERR_MISSING_ACCOUNT = 5;

    // The Op failed because it used relative_to=DEFAULT or LIMIT, but the Account
    // had no Policy attached to it, or if the Op did not include the
    // IGNORE_POLICY_BOUNDS option.
    ERR_POLICY_REQUIRED = 6;
  }
  // Status for this operation.
  OpStatus status = 4;

  // Extra context for `status` as english text. Usually unset, but will be most
  // frequently set for UNKNOWN errors.
  string status_msg = 5;

  // When WITH_POLICY_LIMIT_DELTA option is used, previous_balance_adjusted is
  // set to the previous balance + delta (where delta is the difference between
  // the new Policy.limit and the old Policy.limit). If WITH_POLICY_LIMIT_DELTA
  // is not set or if there is no change in policy_ref, or if the account has no
  // existing policy_ref, previous_balance_adjusted is same as previous_balance.
  int64 previous_balance_adjusted = 6;
}

message ApplyOpsResponse {
  // This is a sequence of results, one per op in the original ApplyOpsRequest.
  //
  // NOTE: The caller must observe the `status` field of each result in order to
  // determine if this request was successful.
  //
  // If any result contains a non-SUCCESS `status`, NONE of the operations have
  // been saved.
  repeated OpResult results = 1;

  // The time this ApplyOpsResponse was created, according to the quota state.
  // Note that for deduplicated requests, this could be fairly old (assuming the
  // original request was made a while ago).
  google.protobuf.Timestamp originally_set = 2;
}

message WritePolicyConfigRequest {
  // If id.version_kind != Manual, id.version will be ignored.
  PolicyConfigID id = 1[
    (validate.rules).message.required = true
  ];

  PolicyConfig policy_config = 2 [
    (validate.rules).message.required = true
  ];
}

message WritePolicyConfigResponse {
  // Returns the computed hash version (or responds with the input `version` if
  // using an application-specific version)
  string version = 1;
}

// Admin exposes an administration API quota state.
service Admin {
  // GetAccounts returns the indicated Accounts.
  rpc GetAccounts(GetAccountsRequest) returns (GetAccountsResponse);

  // ApplyOps updates the available resources with the provided operations.
  rpc ApplyOps(ApplyOpsRequest) returns (ApplyOpsResponse);

  // WritePolicyConfig ingests the given PolicyConfig into the database.
  rpc WritePolicyConfig(WritePolicyConfigRequest) returns (WritePolicyConfigResponse);

  // TODO: ScanAccounts (w/ pattern)
  // TODO: GetPolicyConfigs
  // TODO: ScanPolicyConfigs (w/ pattern)
  // TODO: PurgePolicyConfigs
}