Core Concepts — Object Storage

{
  "name": "demo",
  "description": "Workflow bucket",
  "status": "BUCKET_STATUS_ACTIVE",
  "internalSourceId": "src_01HEFGHIJK",
  "storageUsedBytes": "1048576",
  "storageQuotaBytes": "0",
  "objectCount": "42",
  "sourceCount": "3",
  "ruleCount": "2",
  "indexCount": "1",
  "createdAt": "1700000000000",
  "updatedAt": "1700001000000",
  "accessMode": "BUCKET_ACCESS_MODE_PRIVATE"
}

message Bucket {
  string name = 1;                            // unique per tenant
  string description = 2;
  BucketStatus status = 3;
  string internal_source_id = 4;              // auto-created INTERNAL_S3 source
  int64 storage_used_bytes = 5;
  int64 storage_quota_bytes = 6;              // 0 = unlimited
  int64 object_count = 7;
  int64 source_count = 8;
  int64 rule_count = 9;
  int64 index_count = 10;
  int64 created_at = 11;
  int64 updated_at = 12;
  BucketAccessMode access_mode = 13;
}
 
enum BucketStatus {
  BUCKET_STATUS_UNSPECIFIED = 0;
  BUCKET_STATUS_CREATING = 1;
  BUCKET_STATUS_ACTIVE = 2;
  BUCKET_STATUS_DISABLED = 3;
  BUCKET_STATUS_DELETING = 4;
}
 
enum BucketAccessMode {
  BUCKET_ACCESS_MODE_UNSPECIFIED = 0;         // treated as PRIVATE
  BUCKET_ACCESS_MODE_PRIVATE = 1;
  BUCKET_ACCESS_MODE_PUBLIC = 2;
  BUCKET_ACCESS_MODE_CUSTOM = 3;
}

{
  "bucket": "demo",
  "key": "docs/sample.pdf",
  "size": "1048576",
  "etag": "\"d41d8cd98f00b204e9800998ecf8427e\"",
  "contentType": "application/pdf",
  "lastModified": "1700000500000",
  "userMetadata": {
    "source": "drive"
  },
  "storageClass": "STANDARD",
  "indexStatus": "indexed",
  "pipelineStatuses": [
    {
      "ruleId": "rule_01HEFG",
      "ruleName": "docs-rule",
      "pipelineKind": "vector",
      "indexStatus": "indexed",
      "destinationId": "col_01HIJK"
    }
  ]
}

message ObjectInfo {
  string bucket = 1;
  string key = 2;
  int64 size = 3;
  string etag = 4;
  string content_type = 5;
  int64 last_modified = 6;
  map<string, string> user_metadata = 7;
  string storage_class = 8;
  // Aggregate index status across pipelines: none|pending|indexed|failed|partial
  string index_status = 9;
  // Per-pipeline status (one entry per rule that triggered on this object).
  // The detail fields are flat strings — clients read them directly without
  // pulling in the ingest service types.
  repeated ObjectPipelineStatus pipeline_statuses = 10;
}
 
message ObjectPipelineStatus {
  string rule_id = 1;
  string rule_name = 2;
  string pipeline_kind = 3;                   // "vector" | "warehouse" | "free"
  string index_status = 4;                    // "pending" | "indexed" | "failed" | "partial"
  string destination_id = 5;                  // store_entity.id (empty for free pipelines)
}

{
  "version": "2024-01-01",
  "statements": [
    {
      "sid": "PublicRead",
      "effect": "POLICY_EFFECT_ALLOW",
      "principal": { "aws": ["*"] },
      "actions": ["s3:GetObject"],
      "resources": ["demo/public/*"]
    }
  ]
}

message BucketPolicy {
  string version = 1;                         // e.g. "2024-01-01"
  repeated PolicyStatement statements = 2;
}
 
message PolicyStatement {
  string sid = 1;
  PolicyEffect effect = 2;
  PolicyPrincipal principal = 3;
  repeated string actions = 4;                // "s3:GetObject", "s3:PutObject", ...
  repeated string resources = 5;              // glob patterns
}
 
message PolicyPrincipal {
  repeated string aws = 1;                    // "*" anonymous, or org IDs
}
 
enum PolicyEffect {
  POLICY_EFFECT_UNSPECIFIED = 0;
  POLICY_EFFECT_ALLOW = 1;
  POLICY_EFFECT_DENY = 2;
}

{
  "corsRules": [
    {
      "allowedOrigins": ["https://app.example.com"],
      "allowedMethods": ["GET", "PUT"],
      "allowedHeaders": ["*"],
      "exposeHeaders": ["ETag"],
      "maxAgeSeconds": 3600
    }
  ]
}

message BucketCorsConfiguration {
  repeated CorsRule cors_rules = 1;
}
 
message CorsRule {
  repeated string allowed_origins = 1;
  repeated string allowed_methods = 2;
  repeated string allowed_headers = 3;
  repeated string expose_headers = 4;
  int32 max_age_seconds = 5;
}

// Request body (POST /{bucket}/objects/url)
{
  "bucket": "demo",
  "key": "docs/sample.pdf",
  "expiresInSeconds": "1800"
}
 
// Response
{
  "url": "https://k3.dev.dodil.io/demo/objects/docs%2Fsample.pdf?token=eyJ...",
  "expiresAt": "1700003600000"
}

message GetObjectUrlRequest {
  string bucket = 1;
  string key = 2;
  int64 expires_in_seconds = 3;               // default 3600
}
 
message GetObjectUrlResponse {
  string url = 1;
  int64 expires_at = 2;
}