github.com/authzed/spicedb@v1.32.1-0.20240520085336-ebda56537386/proto/internal/dispatch/v1/dispatch.proto

syntax = "proto3";
package dispatch.v1;

import "core/v1/core.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/struct.proto";
import "validate/validate.proto";

option go_package = "github.com/authzed/spicedb/pkg/proto/dispatch/v1";

service DispatchService {
  rpc DispatchCheck(DispatchCheckRequest) returns (DispatchCheckResponse) {}
  rpc DispatchExpand(DispatchExpandRequest) returns (DispatchExpandResponse) {}

  rpc DispatchReachableResources(DispatchReachableResourcesRequest) returns (stream DispatchReachableResourcesResponse) {}

  rpc DispatchLookupResources(DispatchLookupResourcesRequest) returns (stream DispatchLookupResourcesResponse) {}
  rpc DispatchLookupSubjects(DispatchLookupSubjectsRequest) returns (stream DispatchLookupSubjectsResponse) {}
}

message DispatchCheckRequest {
  enum DebugSetting {
    NO_DEBUG = 0;
    ENABLE_BASIC_DEBUGGING = 1;
    ENABLE_TRACE_DEBUGGING = 2;
  }

  enum ResultsSetting {
    REQUIRE_ALL_RESULTS = 0;
    ALLOW_SINGLE_RESULT = 1;
  }

  ResolverMeta metadata = 1 [(validate.rules).message.required = true];

  core.v1.RelationReference resource_relation = 2 [(validate.rules).message.required = true];
  repeated string resource_ids = 3;

  core.v1.ObjectAndRelation subject = 4 [(validate.rules).message.required = true];

  ResultsSetting results_setting = 5;

  DebugSetting debug = 6;
}

message DispatchCheckResponse {
  ResponseMeta metadata = 1;
  map<string, ResourceCheckResult> results_by_resource_id = 2;
}

message ResourceCheckResult {
  enum Membership {
    UNKNOWN = 0;
    NOT_MEMBER = 1;
    MEMBER = 2;
    CAVEATED_MEMBER = 3;
  }

  Membership membership = 1;
  core.v1.CaveatExpression expression = 2;
  repeated string missing_expr_fields = 3;
}

message DispatchExpandRequest {
  enum ExpansionMode {
    SHALLOW = 0;
    RECURSIVE = 1;
  }

  ResolverMeta metadata = 1 [(validate.rules).message.required = true];

  core.v1.ObjectAndRelation resource_and_relation = 2 [(validate.rules).message.required = true];
  ExpansionMode expansion_mode = 3;
}

message DispatchExpandResponse {
  ResponseMeta metadata = 1;
  core.v1.RelationTupleTreeNode tree_node = 2;
}

message Cursor {
  reserved 1;
  repeated string sections = 2;
  uint32 dispatch_version = 3;
}

message DispatchReachableResourcesRequest {
  ResolverMeta metadata = 1 [(validate.rules).message.required = true];

  core.v1.RelationReference resource_relation = 2 [(validate.rules).message.required = true];
  core.v1.RelationReference subject_relation = 3 [(validate.rules).message.required = true];
  repeated string subject_ids = 4;

  // optional_cursor, if the specified, is the cursor at which to resume returning results. Note
  // that reachableresources can return duplicates.
  Cursor optional_cursor = 5;

  // optional_limit, if given, specifies a limit on the number of resources returned.
  uint32 optional_limit = 6;
}

message ReachableResource {
  enum ResultStatus {
    /**
     * REQUIRES_CHECK indicates that the resource is reachable but a Check is required to
     * determine if the resource is actually found for the user.
     */
    REQUIRES_CHECK = 0;

    /**
     * HAS_PERMISSION indicates that the resource is both reachable and found for the permission
     * for the subject.
     */
    HAS_PERMISSION = 1;
  }

  string resource_id = 1;
  ResultStatus result_status = 2;
  repeated string for_subject_ids = 3;
}

message DispatchReachableResourcesResponse {
  ReachableResource resource = 1;
  ResponseMeta metadata = 2;
  Cursor after_response_cursor = 3;
}

message DispatchLookupResourcesRequest {
  ResolverMeta metadata = 1 [(validate.rules).message.required = true];

  core.v1.RelationReference object_relation = 2 [(validate.rules).message.required = true];
  core.v1.ObjectAndRelation subject = 3 [(validate.rules).message.required = true];
  google.protobuf.Struct context = 5;

  // optional_limit, if given, specifies a limit on the number of resources returned.
  uint32 optional_limit = 4;

  // optional_cursor, if the specified, is the cursor at which to resume returning results. Note
  // that lookupresources can return duplicates.
  Cursor optional_cursor = 6;
}

message ResolvedResource {
  enum Permissionship {
    UNKNOWN = 0;
    HAS_PERMISSION = 1;
    CONDITIONALLY_HAS_PERMISSION = 2;
  }

  string resource_id = 1;
  Permissionship permissionship = 2;
  repeated string missing_required_context = 3;
}

message DispatchLookupResourcesResponse {
  ResponseMeta metadata = 1;
  ResolvedResource resolved_resource = 2;
  Cursor after_response_cursor = 3;
}

message DispatchLookupSubjectsRequest {
  ResolverMeta metadata = 1 [(validate.rules).message.required = true];

  core.v1.RelationReference resource_relation = 2 [(validate.rules).message.required = true];
  repeated string resource_ids = 3;

  core.v1.RelationReference subject_relation = 4
      [ (validate.rules).message.required = true ];

  // optional_limit, if given, specifies a limit on the number of subjects returned. Note that the number
  // returned may be less than this count.
  uint32 optional_limit = 5;

  // optional_cursor, if the specified, is the cursor at which to resume returning results. Note
  // that lookupsubjects can return duplicates.
  Cursor optional_cursor = 6;
}

message FoundSubject {
  string subject_id = 1;
  core.v1.CaveatExpression caveat_expression = 2;
  repeated FoundSubject excluded_subjects = 3;
}

message FoundSubjects {
  repeated FoundSubject found_subjects = 1;
}

message DispatchLookupSubjectsResponse {
  map<string, FoundSubjects> found_subjects_by_resource_id = 1;
  ResponseMeta metadata = 2;
  Cursor after_response_cursor = 3;
}

message ResolverMeta {
  string at_revision = 1 [(validate.rules).string = {max_bytes: 1024}];
  uint32 depth_remaining = 2 [(validate.rules).uint32.gt = 0];
  string request_id = 3 [deprecated = true];
  bytes traversal_bloom = 4 [(validate.rules).bytes = {max_len: 1024}];
}

message ResponseMeta {
  uint32 dispatch_count = 1;
  uint32 depth_required = 2;
  uint32 cached_dispatch_count = 3;

  reserved 4, 5;

  DebugInformation debug_info = 6;
}

message DebugInformation {
  CheckDebugTrace check = 1;
}

message CheckDebugTrace {
  enum RelationType {
    UNKNOWN = 0;
    RELATION = 1;
    PERMISSION = 2;
  }

  DispatchCheckRequest request = 1;
  RelationType resource_relation_type = 2;
  map<string, ResourceCheckResult> results = 3;
  bool is_cached_result = 4;
  repeated CheckDebugTrace sub_problems = 5;
  google.protobuf.Duration duration = 6;
}