frostfs-api/session/types.proto

syntax = "proto3";

package neo.fs.v2.session;

option go_package = "git.frostfs.info/TrueCloudLab/frostfs-api-go/v2/session/grpc;session";
option csharp_namespace = "Neo.FileStorage.API.Session";

import "refs/types.proto";
import "acl/types.proto";
import "status/types.proto";

// Context information for Session Tokens related to ObjectService requests
message ObjectSessionContext {
  // Object request verbs
  enum Verb {
    // Unknown verb
    VERB_UNSPECIFIED = 0;

    // Refers to object.Put RPC call
    PUT = 1;

    // Refers to object.Get RPC call
    GET = 2;

    // Refers to object.Head RPC call
    HEAD = 3;

    // Refers to object.Search RPC call
    SEARCH = 4;

    // Refers to object.Delete RPC call
    DELETE = 5;

    // Refers to object.GetRange RPC call
    RANGE = 6;

    // Refers to object.GetRangeHash RPC call
    RANGEHASH = 7;

    // Refers to object.Patch RPC call
    PATCH = 8;
  }
  // Type of request for which the token is issued
  Verb verb = 1 [ json_name = "verb" ];

  // Carries objects involved in the object session.
  message Target {
    // Indicates which container the session is spread to. Field MUST be set
    // and correct.
    refs.ContainerID container = 1 [ json_name = "container" ];

    // Indicates which objects the session is spread to. Objects are expected
    // to be stored in the FrostFS container referenced by `container` field.
    // Each element MUST have correct format.
    repeated refs.ObjectID objects = 2 [ json_name = "objects" ];
  }
  // Object session target. MUST be correctly formed and set. If `objects`
  // field is not empty, then the session applies only to these elements,
  // otherwise, to all objects from the specified container.
  Target target = 2 [ json_name = "target" ];
}

// Context information for Session Tokens related to ContainerService requests.
message ContainerSessionContext {
  // Container request verbs
  enum Verb {
    // Unknown verb
    VERB_UNSPECIFIED = 0;

    // Refers to container.Put RPC call
    PUT = 1;

    // Refers to container.Delete RPC call
    DELETE = 2;

    // Refers to container.SetExtendedACL RPC call
    SETEACL = 3;
  }
  // Type of request for which the token is issued
  Verb verb = 1 [ json_name = "verb" ];

  // Spreads the action to all owner containers.
  // If set, container_id field is ignored.
  bool wildcard = 2 [ json_name = "wildcard" ];

  // Particular container to which the action applies.
  // Ignored if wildcard flag is set.
  refs.ContainerID container_id = 3 [ json_name = "containerID" ];
}

// FrostFS Session Token.
message SessionToken {
  // Session Token body
  message Body {
    // Token identifier is a valid UUIDv4 in binary form
    bytes id = 1 [ json_name = "id" ];

    // Identifier of the session initiator
    neo.fs.v2.refs.OwnerID owner_id = 2 [ json_name = "ownerID" ];

    // Lifetime parameters of the token. Field names taken from rfc7519.
    message TokenLifetime {
      // Expiration Epoch
      uint64 exp = 1 [ json_name = "exp" ];

      // Not valid before Epoch
      uint64 nbf = 2 [ json_name = "nbf" ];

      // Issued at Epoch
      uint64 iat = 3 [ json_name = "iat" ];
    }
    // Lifetime of the session
    TokenLifetime lifetime = 3 [ json_name = "lifetime" ];

    // Public key used in session
    bytes session_key = 4 [ json_name = "sessionKey" ];

    // Session Context information
    oneof context {
      // ObjectService session context
      ObjectSessionContext object = 5 [ json_name = "object" ];

      // ContainerService session context
      ContainerSessionContext container = 6 [ json_name = "container" ];
    }
  }
  // Session Token contains the proof of trust between peers to be attached in
  // requests for further verification. Please see corresponding section of
  // FrostFS Technical Specification for details.
  Body body = 1 [ json_name = "body" ];

  // Signature of `SessionToken` information
  neo.fs.v2.refs.Signature signature = 2 [ json_name = "signature" ];
}

// Extended headers for Request/Response. They may contain any user-defined
// headers to be interpreted on application level.
//
// Key name must be a unique valid UTF-8 string. Value can't be empty. Requests
// or Responses with duplicated header names or headers with empty values will
// be considered invalid.
//
// There are some "well-known" headers starting with `__SYSTEM__` (`__NEOFS__`
// is deprecated) prefix that affect system behaviour:
//
// * [ __SYSTEM__NETMAP_EPOCH ] \
//   (`__NEOFS__NETMAP_EPOCH` is deprecated) \
//   Netmap epoch to use for object placement calculation. The `value` is string
//   encoded `uint64` in decimal presentation. If set to '0' or not set, the
//   current epoch only will be used.
// * [ __SYSTEM__NETMAP_LOOKUP_DEPTH ] \
//   (`__NEOFS__NETMAP_LOOKUP_DEPTH` is deprecated) \
//   If object can't be found using current epoch's netmap, this header limits
//   how many past epochs the node can look up through. The `value` is string
//   encoded `uint64` in decimal presentation. If set to '0' or not set, only
//   the current epoch will be used.
message XHeader {
  // Key of the X-Header
  string key = 1 [ json_name = "key" ];

  // Value of the X-Header
  string value = 2 [ json_name = "value" ];
}

// Meta information attached to the request. When forwarded between peers,
// request meta headers are folded in matryoshka style.
message RequestMetaHeader {
  // Peer's API version used
  neo.fs.v2.refs.Version version = 1 [ json_name = "version" ];

  // Peer's local epoch number. Set to 0 if unknown.
  uint64 epoch = 2 [ json_name = "epoch" ];

  // Maximum number of intermediate nodes in the request route
  uint32 ttl = 3 [ json_name = "ttl" ];

  // Request X-Headers
  repeated XHeader x_headers = 4 [ json_name = "xHeaders" ];

  // Session token within which the request is sent
  SessionToken session_token = 5 [ json_name = "sessionToken" ];

  // `BearerToken` with eACL overrides for the request
  neo.fs.v2.acl.BearerToken bearer_token = 6 [ json_name = "bearerToken" ];

  // `RequestMetaHeader` of the origin request
  RequestMetaHeader origin = 7 [ json_name = "origin" ];

  // FrostFS network magic. Must match the value for the network
  // that the server belongs to.
  uint64 magic_number = 8 [ json_name = "magicNumber" ];
}

// Information about the response
message ResponseMetaHeader {
  // Peer's API version used
  neo.fs.v2.refs.Version version = 1 [ json_name = "version" ];

  // Peer's local epoch number
  uint64 epoch = 2 [ json_name = "epoch" ];

  // Maximum number of intermediate nodes in the request route
  uint32 ttl = 3 [ json_name = "ttl" ];

  // Response X-Headers
  repeated XHeader x_headers = 4 [ json_name = "xHeaders" ];

  // `ResponseMetaHeader` of the origin request
  ResponseMetaHeader origin = 5 [ json_name = "origin" ];

  // Status return
  neo.fs.v2.status.Status status = 6 [ json_name = "status" ];
}

// Verification info for the request signed by all intermediate nodes.
message RequestVerificationHeader {
  // Request Body signature. Should be generated once by the request initiator.
  neo.fs.v2.refs.Signature body_signature = 1 [ json_name = "bodySignature" ];
  // Request Meta signature is added and signed by each intermediate node
  neo.fs.v2.refs.Signature meta_signature = 2 [ json_name = "metaSignature" ];
  // Signature of previous hops
  neo.fs.v2.refs.Signature origin_signature = 3
      [ json_name = "originSignature" ];

  // Chain of previous hops signatures
  RequestVerificationHeader origin = 4 [ json_name = "origin" ];
}

// Verification info for the response signed by all intermediate nodes
message ResponseVerificationHeader {
  // Response Body signature. Should be generated once by an answering node.
  neo.fs.v2.refs.Signature body_signature = 1 [ json_name = "bodySignature" ];
  // Response Meta signature is added and signed by each intermediate node
  neo.fs.v2.refs.Signature meta_signature = 2 [ json_name = "metaSignature" ];
  // Signature of previous hops
  neo.fs.v2.refs.Signature origin_signature = 3
      [ json_name = "originSignature" ];

  // Chain of previous hops signatures
  ResponseVerificationHeader origin = 4 [ json_name = "origin" ];
}