manager.proto

syntax = "proto3";
package proto;

option go_package="github.com/jimil749/reva-plugin-benchmark/pkg/proto/manager";

// A UserId represents a user.
message UserId {
  // REQUIRED.
  // The identity provider for the user.
  string idp = 1;
  // REQUIRED.
  // the unique identifier for the user in the scope of
  // the identity provider.
  string opaque_id = 2;
  // REQUIRED.
  // The type of user.
  UserType type = 3;
}

// Represents a user of the system.
message User {
  UserId id = 1;
  string username = 2;
  string mail = 3;
  bool mail_verified = 4;
  string display_name = 5;
  repeated string groups = 6;
  Opaque opaque = 7;
  int64 uid_number = 8;
  int64 gid_number = 9;
}

message Opaque {
  // REQUIRED.
  map<string, OpaqueEntry> map = 1;
}

message Status {
  // REQUIRED.
  // The status code, which should be an enum value of [cs3.rpc.code][cs3.rpc.code].
  Code code = 1;
  // OPTIONAL.
  // A developer-facing error message, which should be in English. Any
  // user-facing error message should be localized and sent in the
  string message = 2;
  // OPTIONAL.
  // A trace added to the response for helping support to identify client problems.
  string trace = 3;
  // OPTIONAL.
  // A target URI as per RFC3986 to redirect requests to another location.
  // A Status message with CODE_REDIRECT MUST always set the target_uri.
  // https://golang.org/pkg/net/url/#URL provides a quick view of the format.
  string target_uri = 4;
}

enum Code {
  // A programmer would not intentionally set the code to CODE_INVALID.
  // This code exists to force service implementors to set
  // a specific code for the API call and to not rely on defaults.
  //
  // HTTP Mapping: 500 Internal Server Error
  CODE_INVALID = 0;
  // Not an error; returned on success
  //
  // HTTP Mapping: 200 OK
  CODE_OK = 1;
  // The operation was cancelled, typically by the caller.
  //
  // HTTP Mapping: 499 Client Closed Request
  CODE_CANCELLED = 2;
  // Unknown error.  For example, this error may be returned when
  // a `Status` value received from another address space belongs to
  // an error space that is not known in this address space.  Also
  // errors raised by APIs that do not return enough error information
  // may be converted to this error.
  //
  // HTTP Mapping: 500 Internal Server Error
  CODE_UNKNOWN = 3;
  // The client specified an invalid argument.  Note that this differs
  // from `FAILED_PRECONDITION`.  `INVALID_ARGUMENT` indicates arguments
  // that are problematic regardless of the state of the system
  // (e.g., a malformed file name).
  //
  // HTTP Mapping: 400 Bad Request
  CODE_INVALID_ARGUMENT = 4;
  // The deadline expired before the operation could complete. For operations
  // that change the state of the system, this error may be returned
  // even if the operation has completed successfully.  For example, a
  // successful response from a server could have been delayed long
  // enough for the deadline to expire.
  //
  // HTTP Mapping: 504 Gateway Timeout
  CODE_DEADLINE_EXCEEDED = 5;
  // Some requested entity (e.g., file or directory) was not found.
  //
  // Note to server developers: if a request is denied for an entire class
  // of users, such as gradual feature rollout or undocumented whitelist,
  // `NOT_FOUND` may be used. If a request is denied for some users within
  // a class of users, such as user-based access control, `PERMISSION_DENIED`
  // must be used.
  //
  // HTTP Mapping: 404 Not Found
  CODE_NOT_FOUND = 6;
  // The entity that a client attempted to create (e.g., file or directory)
  // already exists.
  //
  // HTTP Mapping: 409 Conflict
  CODE_ALREADY_EXISTS = 7;
  // The caller does not have permission to execute the specified
  // operation. `PERMISSION_DENIED` must not be used for rejections
  // caused by exhausting some resource (use `RESOURCE_EXHAUSTED`
  // instead for those errors). `PERMISSION_DENIED` must not be
  // used if the caller can not be identified (use `UNAUTHENTICATED`
  // instead for those errors). This error code does not imply the
  // request is valid or the requested entity exists or satisfies
  // other pre-conditions.
  //
  // HTTP Mapping: 403 Forbidden
  CODE_PERMISSION_DENIED = 8;
  // The request does not have valid authentication credentials for the
  // operation.
  //
  // HTTP Mapping: 401 Unauthorized
  CODE_UNAUTHENTICATED = 9;
  // Some resource has been exhausted, perhaps a per-user quota, or
  // perhaps the entire file system is out of space.
  //
  // HTTP Mapping: 429 Too Many Requests
  CODE_RESOURCE_EXHAUSTED = 10;
  // The operation was rejected because the system is not in a state
  // required for the operation's execution.  For example, the directory
  // to be deleted is non-empty, an rmdir operation is applied to
  // a non-directory, etc.
  //
  // Service implementors can use the following guidelines to decide
  // between `FAILED_PRECONDITION`, `ABORTED`, and `UNAVAILABLE`:
  //  (a) Use `UNAVAILABLE` if the client can retry just the failing call.
  //  (b) Use `ABORTED` if the client should retry at a higher level
  //      (e.g., when a client-specified test-and-set fails, indicating the
  //      client should restart a read-modify-write sequence).
  //  (c) Use `FAILED_PRECONDITION` if the client should not retry until
  //      the system state has been explicitly fixed.  E.g., if an "rmdir"
  //      fails because the directory is non-empty, `FAILED_PRECONDITION`
  //      should be returned since the client should not retry unless
  //      the files are deleted from the directory.
  //
  // HTTP Mapping: 400 Bad Request
  CODE_FAILED_PRECONDITION = 11;
  // The operation was aborted, typically due to a concurrency issue such as
  // a sequencer check failure or transaction abort.
  //
  // See the guidelines above for deciding between `FAILED_PRECONDITION`,
  // `ABORTED`, and `UNAVAILABLE`.
  //
  // HTTP Mapping: 409 Conflict
  CODE_ABORTED = 12;
  // The operation was attempted past the valid range.  E.g., seeking or
  // reading past end-of-file.
  //
  // Unlike `INVALID_ARGUMENT`, this error indicates a problem that may
  // be fixed if the system state changes. For example, a 32-bit file
  // system will generate `INVALID_ARGUMENT` if asked to read at an
  // offset that is not in the range [0,2^32-1], but it will generate
  // `OUT_OF_RANGE` if asked to read from an offset past the current
  // file size.
  //
  // There is a fair bit of overlap between `FAILED_PRECONDITION` and
  // `OUT_OF_RANGE`.  We recommend using `OUT_OF_RANGE` (the more specific
  // error) when it applies so that callers who are iterating through
  // a space can easily look for an `OUT_OF_RANGE` error to detect when
  // they are done.
  //
  // HTTP Mapping: 400 Bad Request
  CODE_OUT_OF_RANGE = 13;
  // The operation is not implemented or is not supported/enabled in this
  // service.
  //
  // HTTP Mapping: 501 Not Implemented
  CODE_UNIMPLEMENTED = 14;
  // Internal errors.  This means that some invariants expected by the
  // underlying system have been broken.  This error code is reserved
  // for serious errors.
  //
  // HTTP Mapping: 500 Internal Server Error
  CODE_INTERNAL = 15;
  // The service is currently unavailable.  This is most likely a
  // transient condition, which can be corrected by retrying with
  // a backoff.
  //
  // See the guidelines above for deciding between `FAILED_PRECONDITION`,
  // `ABORTED`, and `UNAVAILABLE`.
  //
  // HTTP Mapping: 503 Service Unavailable
  CODE_UNAVAILABLE = 16;
  // Unrecoverable data loss or corruption.
  //
  // HTTP Mapping: 500 Internal Server Error
  CODE_DATA_LOSS = 17;
  // Redirects the operation to another location.
  // Used in a Status reponse with a reference to the target URI.
  CODE_REDIRECTION = 18;
  //
  // The operation could not be performed because there is not enough
  // storage available. This can be because of lack of real storage
  // space or because of the exceeding of a quota associated to a
  // storage.
  //
  // HTTP Mapping: 507 Insufficient Storage
  CODE_INSUFFICIENT_STORAGE = 19;
}

// OpaqueEntry represents the encoded
// opaque value.
message OpaqueEntry {
  // REQUIRED.
  // The decoder to use: json, xml, toml, ...
  // TODO(labkode): make encoder a fixed set using a enum type?
  string decoder = 1;
  // REQUIRED.
  // The encoded value.
  bytes value = 2;
}

// The type of user.
enum UserType {
  // The user is invalid, for example, is missing primary attributes.
  USER_TYPE_INVALID = 0;
  // A primary user.
  USER_TYPE_PRIMARY = 1;
  // A secondary user for cases with multiple identities.
  USER_TYPE_SECONDARY = 2;
  // A user catering to specific services.
  USER_TYPE_SERVICE = 3;
  // A user to be used by specific applications.
  USER_TYPE_APPLICATION = 4;
  // A guest user not affiliated to the IDP.
  USER_TYPE_GUEST = 5;
  // A federated user provided by external IDPs.
  USER_TYPE_FEDERATED = 6;
  // A lightweight user account without access to various major functionalities.
  USER_TYPE_LIGHTWEIGHT = 7;
}

// Provides an API for managing users.
service UserAPI {
  // Load the plugin
  rpc OnLoad(OnLoadRequest) returns (OnLoadResponse);
  // Gets the information about a user by the user id.
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
  // Gets the information about a user based on a specified claim.
  rpc GetUserByClaim(GetUserByClaimRequest) returns (GetUserByClaimResponse);
  // Gets the groups of a user.
  rpc GetUserGroups(GetUserGroupsRequest) returns (GetUserGroupsResponse);
  // Finds users by any attribute of the user.
  // TODO(labkode): to define the filters that make more sense.
  rpc FindUsers(FindUsersRequest) returns (FindUsersResponse);
}

message OnLoadRequest {
  string UserFile = 1;
}

message OnLoadResponse{}

message GetUserRequest {
  // OPTIONAL.
  // Opaque information.
  Opaque opaque = 1;
  // REQUIRED.
  // The id of the user.
  UserId user_id = 2;
}

message GetUserResponse {
  // REQUIRED.
  // The response status.
  Status status = 1;
  // OPTIONAL.
  // Opaque information.
  Opaque opaque = 2;
  // REQUIRED.
  // The user information.
  User user = 3;
}

message GetUserByClaimRequest {
  // OPTIONAL.
  // Opaque information.
  Opaque opaque = 1;
  // REQUIRED.
  // The claim on the basis of which users will be filtered.
  string claim = 2;
  // REQUIRED.
  // The value of the claim to find the specific user.
  string value = 3;
}

message GetUserByClaimResponse {
  // REQUIRED.
  // The response status.
  Status status = 1;
  // OPTIONAL.
  // Opaque information.
  Opaque opaque = 2;
  // REQUIRED.
  // The user information.
  User user = 3;
}

message GetUserGroupsRequest {
  // OPTIONAL.
  // Opaque information.
  Opaque opaque = 1;
  // REQUIRED.
  // The id of the user.
  UserId user_id = 2;
}

message GetUserGroupsResponse {
  // REQUIRED.
  // The response status.
  Status status = 1;
  // OPTIONAL.
  // Opaque information.
  Opaque opaque = 2;
  // REQUIRED.
  // The groups for the user.
  repeated string groups = 3;
}

message FindUsersRequest {
  // OPTIONAL.
  // Opaque information.
  Opaque opaque = 1;
  // REQUIRED. TODO(labkode): create proper filters for most common searches.
  // The filter to apply.
  string filter = 2;
}

message FindUsersResponse {
  // REQUIRED.
  // The response status.
  Status status = 1;
  // OPTIONAL.
  // Opaque information.
  Opaque opaque = 2;
  // REQUIRED.
  // The users matching the specified filter.
  repeated User users = 3;
}