kessel-sdk 1.7.0 → 1.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ebc4d755f68e6022b70351cb5320d50150f99909d2c41abff3dc356f99d543e0
-  data.tar.gz: e3023bf1171a3ae11021393dc16640cdbe9c28fdff55120f3717dfd6985b1e05
+  metadata.gz: 9408aacf7604105abff5b811ad6548270be6d0c63f6193602fecd703ea79d522
+  data.tar.gz: 0237cd7effe27b00ff1ac07b1e8a2121f0275a2cbd48e215ae0a24ad511e8fb3
 SHA512:
-  metadata.gz: 787acd87560a9a3e563ef6abb46eba11ea94a14d418798a8124d2f63c768a561321434ec0291652147377f8f53dc8092a46a0ac202d16d8366516aa9bf76c844
-  data.tar.gz: 1a8aa9c31fdef9a382eadf8fcfa9bd0cf096549e4119c1c2256cdca85659a4cff814fe7ad718ec108bfaeb5dcb4f7589866c378e66fd5564a12be97999f74320
+  metadata.gz: 6a6ee646283375fcb8f535f14475639e1d9b687212de54c06795eab2de4b07abc310a74c0ba9ed5d660efbcf8a039929f3cf6379ebaae18f8859434324fdd565
+  data.tar.gz: 6a92e7bb7b73d215fade25f2e818ecfad57638d5f84858c742fd4914294ac90132205cd9e252cb8906729927508fe73ba662e0fe93ee9e6528629be421137448

data/README.md

@@ -2,7 +2,9 @@
 
 [![CI](https://github.com/project-kessel/kessel-sdk-ruby/actions/workflows/ci.yml/badge.svg)](https://github.com/project-kessel/kessel-sdk-ruby/actions/workflows/ci.yml)
 
-A Ruby gRPC library for connecting to [Project Kessel](https://github.com/project-kessel) services. This provides the foundational gRPC client library for Kessel Inventory API, with plans for a higher-level SDK with fluent APIs, OAuth support, and advanced features in future releases.
+The official Ruby gRPC client SDK for [Project Kessel](https://github.com/project-kessel) services. It provides generated protobuf/gRPC bindings for the Kessel Inventory API, a fluent client builder with credential validation, OAuth 2.0 Client Credentials authentication (via OIDC), and RBAC convenience helpers for workspace operations.
+
+Published on RubyGems as [`kessel-sdk`](https://rubygems.org/gems/kessel-sdk).
 
 ## Installation
 
@@ -24,7 +26,7 @@ Or install it yourself as:
 gem install kessel-sdk
 ```
 
-## Authentication (Optional)
+### Authentication (Optional)
 
 The SDK supports OAuth 2.0 Client Credentials flow. To use authentication features, add the OpenID Connect gem:
 
@@ -33,21 +35,103 @@ gem 'kessel-sdk'
 gem 'openid_connect', '~> 2.0'  # Optional - only for authentication
 ```
 
+The `openid_connect` gem is intentionally not a hard runtime dependency. Consumers who do not need OAuth are not forced to install it or its transitive dependencies.
+
+## Project Structure
+
+```
+lib/
+  kessel-sdk.rb              # Single entrypoint (require 'kessel-sdk')
+  kessel/
+    auth.rb                  # OAuth2 Client Credentials, OIDC discovery
+    grpc.rb                  # gRPC credential helpers
+    inventory.rb             # ClientBuilder base class, client_builder_for_stub
+    version.rb               # Kessel::Inventory::VERSION
+    inventory/
+      v1/                    # Health check service (stable)
+      v1beta1/               # Legacy typed K8s resources/relationships
+      v1beta2/               # Current unified inventory service (primary API)
+    rbac/
+      v2.rb                  # Workspace fetch, list_workspaces enumerator
+      v2_helpers.rb          # Factory methods for protobuf references
+      v2_http.rb             # HTTP request helpers for RBAC API
+sig/                         # RBS type signatures for hand-written code
+spec/                        # RSpec test suite
+examples/                    # Working examples with dotenv configuration
+docs/                        # Domain-specific guidelines (see Documentation below)
+```
+
+Files under `lib/kessel/inventory/v*/`, `lib/google/`, and `lib/buf/` are **generated** by `buf generate` and must never be hand-edited. They are automatically regenerated every 6 hours via CI.
+
 ## Usage
 
-This library provides direct access to Kessel Inventory API gRPC services. All generated classes are available under the `Kessel::Inventory` module.
+Load the complete SDK via the single entrypoint:
 
-### Basic Example - Check Permissions
+```ruby
+require 'kessel-sdk'
+```
+
+### Building a Client
+
+The recommended way to create gRPC clients is with the **`ClientBuilder` fluent API**, which enforces credential validation at configuration time. Every gRPC service module exposes a `ClientBuilder` constant.
+
+#### Insecure (Development Only)
 
 ```ruby
-require 'kessel/inventory/v1beta2/inventory_service_services_pb'
+include Kessel::Inventory::V1beta2
+
+client = KesselInventoryService::ClientBuilder.new('localhost:9000')
+                                              .insecure
+                                              .build
+```
+
+#### OAuth2 Client Credentials (Production)
+
+```ruby
+include Kessel::Inventory::V1beta2
+include Kessel::Auth
+
+# Discover the token endpoint via OIDC
+discovery = fetch_oidc_discovery('https://sso.example.com/auth/realms/my-realm')
+
+# Create OAuth2 credentials
+oauth = OAuth2ClientCredentials.new(
+  client_id: 'my-app',
+  client_secret: 'my-secret',
+  token_endpoint: discovery.token_endpoint
+)
+
+# Build the client -- tokens are cached and refreshed automatically
+client = KesselInventoryService::ClientBuilder.new('kessel.example.com:443')
+                                              .oauth2_client_authenticated(oauth2_client_credentials: oauth)
+                                              .build
+```
+
+#### Custom or No Credentials
+
+```ruby
+# Custom call/channel credentials
+client = KesselInventoryService::ClientBuilder.new(target)
+                                              .authenticated(call_credentials: creds, channel_credentials: ch_creds)
+                                              .build
+
+# No call credentials (TLS channel only)
+client = KesselInventoryService::ClientBuilder.new(target)
+                                              .unauthenticated
+                                              .build
+```
+
+Build the client **once at application startup and reuse it**. The underlying gRPC channel manages its own HTTP/2 connection pool.
 
+### Check Permissions
+
+```ruby
 include Kessel::Inventory::V1beta2
 
-# Create gRPC client (insecure for development)
-client = KesselInventoryService::Stub.new('localhost:9000', :this_channel_is_insecure)
+client = KesselInventoryService::ClientBuilder.new('localhost:9000')
+                                              .insecure
+                                              .build
 
-# Create subject reference
 subject_reference = SubjectReference.new(
   resource: ResourceReference.new(
     reporter: ReporterReference.new(type: 'rbac'),
@@ -56,14 +140,12 @@ subject_reference = SubjectReference.new(
   )
 )
 
-# Create resource reference
 resource = ResourceReference.new(
   reporter: ReporterReference.new(type: 'rbac'),
   resource_id: 'workspace456',
   resource_type: 'workspace'
 )
 
-# Check permissions
 begin
   response = client.check(
     CheckRequest.new(
@@ -73,80 +155,95 @@ begin
     )
   )
   puts "Permission check result: #{response.allowed}"
-rescue => e
-  puts "Error: #{e.message}"
+rescue GRPC::BadStatus => e
+  puts "gRPC error: #{e.message}"
 end
 ```
 
-### Report Resource Example
+### Bulk Permission Checks
 
 ```ruby
-require 'kessel/inventory/v1beta2/inventory_service_services_pb'
-
 include Kessel::Inventory::V1beta2
-
-client = KesselInventoryService::Stub.new('localhost:9000', :this_channel_is_insecure)
-
-# Report a new resource
-resource_data = {
-  'apiVersion' => 'v1',
-  'kind' => 'Namespace', 
-  'metadata' => {
-    'name' => 'my-namespace',
-    'uid' => '12345'
-  }
-}
-
-request = ReportResourceRequest.new(
-  resource: ResourceRepresentations.new(
-    kessel_inventory: {
-      metadata: RepresentationMetadata.new(
-        resource_type: 'k8s-namespace',
-        resource_id: resource_data['metadata']['uid'],
-        workspace: 'default'
-      )
-    },
-    k8s_manifest: resource_data.to_json
-  )
+include Kessel::RBAC::V2
+
+client = KesselInventoryService::ClientBuilder.new('localhost:9000')
+                                              .insecure
+                                              .build
+
+response = client.check_bulk(
+  CheckBulkRequest.new(items: [
+    CheckBulkRequestItem.new(
+      object: workspace_resource('workspace_123'),
+      relation: 'view_widget',
+      subject: principal_subject('bob', 'redhat')
+    ),
+    CheckBulkRequestItem.new(
+      object: workspace_resource('workspace_456'),
+      relation: 'use_widget',
+      subject: principal_subject('alice', 'redhat')
+    )
+  ])
 )
 
-begin
-  response = client.report_resource(request)
-  puts "Resource reported successfully"
-rescue => e
-  puts "Error reporting resource: #{e.message}"
+response.pairs.each do |pair|
+  if pair.item
+    puts "Allowed: #{pair.item.allowed}"
+  elsif pair.error
+    puts "Error: #{pair.error.message}"
+  end
 end
 ```
 
-### Available Services
+### List Workspaces (Streaming with Auto-Pagination)
 
-The library includes the following gRPC services:
+```ruby
+include Kessel::Inventory::V1beta2
+include Kessel::RBAC::V2
+
+client = KesselInventoryService::ClientBuilder.new('localhost:9000')
+                                              .insecure
+                                              .build
 
-- **KesselInventoryService**: Main inventory service
-  - `check(CheckRequest)` - Check permissions
-  - `check_for_update(CheckForUpdateRequest)` - Check for resource updates  
-  - `report_resource(ReportResourceRequest)` - Report resource state
-  - `delete_resource(DeleteResourceRequest)` - Delete a resource
-  - `streamed_list_objects(StreamedListObjectsRequest)` - Stream resource listings
+list_workspaces(client, principal_subject('alice', 'redhat'), 'view_document').each do |response|
+  puts response
+end
+```
 
-### Generated Classes
+### Available Services (V1beta2)
 
-All protobuf message classes are generated and available. Key classes include:
+The primary service is **`KesselInventoryService`** with these RPCs:
 
-- `CheckRequest`, `CheckResponse`
-- `ReportResourceRequest`, `ReportResourceResponse` 
-- `DeleteResourceRequest`, `DeleteResourceResponse`
-- `ResourceReference`, `SubjectReference`
-- `ResourceRepresentations`, `RepresentationMetadata`
+| RPC | Description |
+|-----|-------------|
+| `check` | Check if a subject has a relation on a resource |
+| `check_self` | Check using the caller's identity from auth context |
+| `check_for_update` | Strongly consistent check (use before writes) |
+| `check_bulk` | Batch permission checks (up to 1000 items) |
+| `check_self_bulk` | Batch self-checks |
+| `check_for_update_bulk` | Batch strongly consistent checks |
+| `report_resource` | Report resource state to inventory |
+| `delete_resource` | Delete a resource from inventory |
+| `streamed_list_objects` | Stream objects a subject has a relation to |
+| `streamed_list_subjects` | Stream subjects that have a relation to a resource |
 
-See the `examples/` directory for complete working examples.
+### RBAC Helper Methods
+
+The `Kessel::RBAC::V2` module provides factory methods for common protobuf references (all use `reporter_type: 'rbac'`):
+
+- `workspace_resource(id)` / `role_resource(id)` -- `ResourceReference` factories
+- `principal_resource(id, domain)` -- `ResourceReference` with ID formatted as `"domain/id"`
+- `principal_subject(id, domain)` -- `SubjectReference` wrapping a principal resource
+- `subject(resource_ref, relation)` -- generic `SubjectReference` factory
+- `fetch_default_workspace(endpoint, org_id, auth:, http_client:)` -- fetch default workspace via RBAC HTTP API
+- `fetch_root_workspace(endpoint, org_id, auth:, http_client:)` -- fetch root workspace via RBAC HTTP API
+- `list_workspaces(inventory, subject, relation)` -- lazy `Enumerator` with auto-pagination
 
 ## Type Safety
 
 This library includes RBS type signatures for enhanced type safety in Ruby. The type definitions are located in the `sig/` directory and cover:
 
 - Core library interfaces
-- Configuration structures  
+- Configuration structures
 - OAuth authentication classes
 - gRPC client builders
 
@@ -156,7 +253,7 @@ To use with type checkers like Steep or Sorbet, ensure the `sig/` directory is i
 
 ### Prerequisites
 
-- Ruby 3.3 or higher  
+- Ruby 3.3 or higher
 - [buf](https://buf.build) for protobuf/gRPC code generation
 
 Install buf:
@@ -219,29 +316,43 @@ rake install_local
 
 ## Examples
 
-The `examples/` directory contains working examples:
-
-- `check.rb` - Permission checking
-- `report_resource.rb` - Reporting resource state
-- `delete_resource.rb` - Deleting resources
-- `check_for_update.rb` - Checking for updates
-- `streamed_list_objects.rb` - Streaming resource lists
+The `examples/` directory contains working examples. Set up environment variables in `examples/.env` before running.
+
+| Example | Description |
+|---------|-------------|
+| `auth.rb` | OAuth 2.0 authentication with ClientBuilder |
+| `check.rb` | Permission checking |
+| `check_bulk.rb` | Bulk permission checks |
+| `check_for_update.rb` | Strongly consistent update checks |
+| `check_for_update_bulk.rb` | Bulk strongly consistent update checks |
+| `delete_resource.rb` | Deleting resources |
+| `fetch_workspaces.rb` | Fetching workspaces via RBAC HTTP API |
+| `list_workspaces.rb` | Listing workspaces with auto-pagination |
+| `report_resource.rb` | Reporting resource state |
+| `console_principal.rb` | Building principals from `x-rh-identity` headers |
+| `streamed_list_objects.rb` | Streaming resource lists |
 
 Run examples:
 
 ```bash
 cd examples
+bundle install
 ruby check.rb
 ```
 
-## Roadmap
+## Documentation
+
+Detailed domain-specific guidelines are maintained in the `docs/` directory:
+
+- **[API Contracts](docs/api-contracts-guidelines.md)** -- Protobuf code generation, module/namespace mapping, ClientBuilder API, request/response patterns, and RBS type signatures
+- **[Integration](docs/integration-guidelines.md)** -- gRPC client construction, authentication flows, RBAC helpers, streaming/pagination, and environment configuration
+- **[Security](docs/security-guidelines.md)** -- Token caching thread safety, gRPC channel security, credential validation, and secrets management
+- **[Performance](docs/performance-guidelines.md)** -- Token caching, gRPC client reuse, bulk vs. individual operations, consistency controls, and streaming pagination
+- **[Error Handling](docs/error-handling-guidelines.md)** -- Custom exception hierarchy, error wrapping conventions, and gRPC error passthrough policy
+- **[Testing](docs/testing-guidelines.md)** -- RSpec configuration, mocking conventions, coverage setup, and CI expectations
 
-This is the foundational gRPC library. Future releases will include:
+For AI-assisted development context, see [AGENTS.md](AGENTS.md).
 
-- **High-level SDK**: Fluent client builder API
-- **Authentication**: OAuth 2.0 Client Credentials flow
-- **Convenience Methods**: Simplified APIs for common operations*
-*
 ## Release Instructions
 
 This section provides step-by-step instructions for maintainers to release a new version of the Kessel SDK for Ruby.
@@ -251,7 +362,7 @@ This section provides step-by-step instructions for maintainers to release a new
 This project follows [Semantic Versioning 2.0.0](https://semver.org/). Version numbers use the format `MAJOR.MINOR.PATCH`:
 
 - **MAJOR**: Increment for incompatible API changes
-- **MINOR**: Increment for backward-compatible functionality additions  
+- **MINOR**: Increment for backward-compatible functionality additions
 - **PATCH**: Increment for backward-compatible bug fixes
 
 **Note**: SDK versions across different languages (Ruby, Python, Go, etc.) do not need to be synchronized. Each language SDK can evolve independently based on its specific requirements and release schedule.
@@ -269,12 +380,17 @@ This project follows [Semantic Versioning 2.0.0](https://semver.org/). Version n
 
 1. **Update the Version**
    ```bash
-   # Edit lib/kessel/version.rb
-   # Update the VERSION constant to the new version number
+   # Edit lib/kessel/version.rb and update the VERSION constant
    vim lib/kessel/version.rb
    ```
 
-2. **Update Dependencies**
+2. **Set the VERSION environment variable**
+   ```bash
+   export VERSION=$(ruby -e "require_relative './lib/kessel/version.rb'; puts Kessel::Inventory::VERSION")
+   echo "Releasing version: v${VERSION}"
+   ```
+
+3. **Update Dependencies**
    ```bash
    # Generate gRPC code from Kessel Inventory API
    buf generate
@@ -282,7 +398,7 @@ This project follows [Semantic Versioning 2.0.0](https://semver.org/). Version n
    bundle install
    ```
 
-3. **Run Quality Checks**
+4. **Run Quality Checks**
    ```bash
    # Run the full test suite
    bundle exec rspec
@@ -297,15 +413,14 @@ This project follows [Semantic Versioning 2.0.0](https://semver.org/). Version n
    rake install_local
    ```
 
-4. **Commit Changes**
+5. **Commit Changes**
    ```bash
-   export VERSION=$(ruby -e "require_relative './lib/kessel/version.rb'; puts Kessel::Inventory::VERSION")
    git add lib/kessel/version.rb Gemfile.lock
    git commit -m "Release version ${VERSION}"
    git push origin main # or git push upstream main
    ```
 
-5. **Build and Release the Gem**
+6. **Build and Release the Gem**
    ```bash
    # Build the gem
    gem build kessel-sdk.gemspec
@@ -314,21 +429,27 @@ This project follows [Semantic Versioning 2.0.0](https://semver.org/). Version n
    gem push kessel-sdk-${VERSION}.gem
    ```
 
-6. **Tag the Release**
+7. **Tag the Release**
    ```bash
    # Create and push a git tag
    git tag -a v${VERSION} -m "Release version ${VERSION}"
    git push origin v${VERSION} # or git push upstream v${VERSION} 
    ```
 
-7. **Create a new release in github**
-- Go to the [GitHub Releases page](https://github.com/project-kessel/kessel-sdk-ruby/releases)
-- Click "Create a new release"
-- Select the tag you just created
-- Add release notes describing the changes
-- Publish the release
+8. **Create GitHub Release**
+   ```bash
+   gh release create v${VERSION} --title "v${VERSION}" --generate-notes
+   ```
 
-8. **Clean Up**
+   Or manually:
+
+   - Go to the [GitHub Releases page](https://github.com/project-kessel/kessel-sdk-ruby/releases)
+   - Click "Create a new release"
+   - Select the tag you just created
+   - Add release notes describing the changes
+   - Publish the release
+
+9. **Clean Up**
    ```bash
    # Remove the built gem file
    rake clean
@@ -352,7 +473,7 @@ rake install
 rake release
 ```
 
-**Note**: The `rake release` command automates steps 5-6 above but requires proper git and RubyGems credentials to be configured.
+**Note**: The `rake release` command automates steps 6-7 above but requires proper git and RubyGems credentials to be configured.
 
 ## Contributing
 
@@ -362,6 +483,8 @@ rake release
 4. Push to the branch (`git push origin feature/amazing-feature`)
 5. Open a Pull Request
 
+Please review the [domain-specific guidelines](docs/) before contributing. All specs must pass on Ruby 3.3 and 3.4. Fix RuboCop violations before merging, and update RBS type signatures in `sig/kessel/` when modifying hand-written code.
+
 ## License
 
 This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

data/lib/kessel/console.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'base64'
+require_relative 'rbac/v2_helpers'
+
+module Kessel
+  module Console
+    include Kessel::RBAC::V2
+    extend self
+
+    DEFAULT_DOMAIN = 'redhat'
+
+    IDENTITY_TYPE_FIELDS = {
+      'User' => 'user',
+      'ServiceAccount' => 'service_account'
+    }.freeze
+
+    def principal_from_rh_identity(identity, domain: DEFAULT_DOMAIN)
+      user_id = extract_user_id(identity)
+      principal_subject(user_id, domain)
+    end
+
+    def principal_from_rh_identity_header(header, domain: DEFAULT_DOMAIN)
+      decoded = JSON.parse(Base64.decode64(header))
+    rescue StandardError => e
+      raise ArgumentError, "Failed to decode identity header: #{e.message}"
+    else
+      raise ArgumentError, 'Identity header did not decode to a JSON object' unless decoded.is_a?(Hash)
+
+      identity = decoded['identity']
+      raise ArgumentError, "Identity header is missing the 'identity' envelope key" if identity.nil?
+
+      principal_from_rh_identity(identity, domain: domain)
+    end
+
+    private
+
+    def extract_user_id(identity)
+      raise ArgumentError, 'identity must be a Hash' unless identity.is_a?(Hash)
+
+      identity_type = identity['type']
+      field = identity_field_for(identity_type)
+      details = identity_details_for(identity, field, identity_type)
+      resolve_user_id(details, identity_type)
+    end
+
+    def identity_field_for(identity_type)
+      IDENTITY_TYPE_FIELDS.fetch(identity_type) do
+        supported = IDENTITY_TYPE_FIELDS.keys.sort.join(', ')
+        raise ArgumentError, "Unsupported identity type: #{identity_type.inspect} (supported: #{supported})"
+      end
+    end
+
+    def identity_details_for(identity, field, identity_type)
+      details = identity[field]
+      unless details.is_a?(Hash)
+        raise ArgumentError, "Identity type #{identity_type.inspect} is missing the '#{field}' field"
+      end
+
+      details
+    end
+
+    def resolve_user_id(details, identity_type)
+      user_id = details['user_id'].to_s
+      raise ArgumentError, "Unable to resolve user ID from #{identity_type} identity (tried: user_id)" if user_id.empty?
+
+      user_id
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/check_for_update_bulk_request_pb.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/check_for_update_bulk_request.proto
+
+require 'google/protobuf'
+
+require 'buf/validate/validate_pb'
+require 'kessel/inventory/v1beta2/check_bulk_request_pb'
+
+
+descriptor_data = "\n<kessel/inventory/v1beta2/check_for_update_bulk_request.proto\x12\x18kessel.inventory.v1beta2\x1a\x1b\x62uf/validate/validate.proto\x1a\x31kessel/inventory/v1beta2/check_bulk_request.proto\"n\n\x19\x43heckForUpdateBulkRequest\x12Q\n\x05items\x18\x01 \x03(\x0b\x32..kessel.inventory.v1beta2.CheckBulkRequestItemB\x0b\xbaH\x08\x92\x01\x05\x08\x01\x10\xe8\x07R\x05itemsBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      CheckForUpdateBulkRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.CheckForUpdateBulkRequest").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/check_for_update_bulk_response_pb.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/check_for_update_bulk_response.proto
+
+require 'google/protobuf'
+
+require 'kessel/inventory/v1beta2/check_bulk_request_pb'
+require 'kessel/inventory/v1beta2/consistency_token_pb'
+require 'kessel/inventory/v1beta2/allowed_pb'
+require 'buf/validate/validate_pb'
+require 'google/rpc/status_pb'
+
+
+descriptor_data = "\n=kessel/inventory/v1beta2/check_for_update_bulk_response.proto\x12\x18kessel.inventory.v1beta2\x1a\x31kessel/inventory/v1beta2/check_bulk_request.proto\x1a\x30kessel/inventory/v1beta2/consistency_token.proto\x1a&kessel/inventory/v1beta2/allowed.proto\x1a\x1b\x62uf/validate/validate.proto\x1a\x17google/rpc/status.proto\"]\n\x1e\x43heckForUpdateBulkResponseItem\x12;\n\x07\x61llowed\x18\x01 \x01(\x0e\x32!.kessel.inventory.v1beta2.AllowedR\x07\x61llowed\"\xf2\x01\n\x1e\x43heckForUpdateBulkResponsePair\x12H\n\x07request\x18\x01 \x01(\x0b\x32..kessel.inventory.v1beta2.CheckBulkRequestItemR\x07request\x12N\n\x04item\x18\x02 \x01(\x0b\x32\x38.kessel.inventory.v1beta2.CheckForUpdateBulkResponseItemH\x00R\x04item\x12*\n\x05\x65rror\x18\x03 \x01(\x0b\x32\x12.google.rpc.StatusH\x00R\x05\x65rrorB\n\n\x08response\"\xcf\x01\n\x1a\x43heckForUpdateBulkResponse\x12X\n\x05pairs\x18\x01 \x03(\x0b\x32\x38.kessel.inventory.v1beta2.CheckForUpdateBulkResponsePairB\x08\xbaH\x05\x92\x01\x02\x08\x01R\x05pairs\x12W\n\x11\x63onsistency_token\x18\x02 \x01(\x0b\x32*.kessel.inventory.v1beta2.ConsistencyTokenR\x10\x63onsistencyTokenBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      CheckForUpdateBulkResponseItem = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.CheckForUpdateBulkResponseItem").msgclass
+      CheckForUpdateBulkResponsePair = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.CheckForUpdateBulkResponsePair").msgclass
+      CheckForUpdateBulkResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.CheckForUpdateBulkResponse").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/inventory_service_pb.rb

@@ -15,15 +15,19 @@ require 'kessel/inventory/v1beta2/delete_resource_request_pb'
 require 'kessel/inventory/v1beta2/delete_resource_response_pb'
 require 'kessel/inventory/v1beta2/streamed_list_objects_request_pb'
 require 'kessel/inventory/v1beta2/streamed_list_objects_response_pb'
+require 'kessel/inventory/v1beta2/streamed_list_subjects_request_pb'
+require 'kessel/inventory/v1beta2/streamed_list_subjects_response_pb'
 require 'kessel/inventory/v1beta2/check_bulk_request_pb'
 require 'kessel/inventory/v1beta2/check_bulk_response_pb'
 require 'kessel/inventory/v1beta2/check_self_request_pb'
 require 'kessel/inventory/v1beta2/check_self_response_pb'
 require 'kessel/inventory/v1beta2/check_self_bulk_request_pb'
 require 'kessel/inventory/v1beta2/check_self_bulk_response_pb'
+require 'kessel/inventory/v1beta2/check_for_update_bulk_request_pb'
+require 'kessel/inventory/v1beta2/check_for_update_bulk_response_pb'
 
 
-descriptor_data = "\n0kessel/inventory/v1beta2/inventory_service.proto\x12\x18kessel.inventory.v1beta2\x1a\x1cgoogle/api/annotations.proto\x1a,kessel/inventory/v1beta2/check_request.proto\x1a-kessel/inventory/v1beta2/check_response.proto\x1a\x37kessel/inventory/v1beta2/check_for_update_request.proto\x1a\x38kessel/inventory/v1beta2/check_for_update_response.proto\x1a\x36kessel/inventory/v1beta2/report_resource_request.proto\x1a\x37kessel/inventory/v1beta2/report_resource_response.proto\x1a\x36kessel/inventory/v1beta2/delete_resource_request.proto\x1a\x37kessel/inventory/v1beta2/delete_resource_response.proto\x1a<kessel/inventory/v1beta2/streamed_list_objects_request.proto\x1a=kessel/inventory/v1beta2/streamed_list_objects_response.proto\x1a\x31kessel/inventory/v1beta2/check_bulk_request.proto\x1a\x32kessel/inventory/v1beta2/check_bulk_response.proto\x1a\x31kessel/inventory/v1beta2/check_self_request.proto\x1a\x32kessel/inventory/v1beta2/check_self_response.proto\x1a\x36kessel/inventory/v1beta2/check_self_bulk_request.proto\x1a\x37kessel/inventory/v1beta2/check_self_bulk_response.proto2\xc7\t\n\x16KesselInventoryService\x12~\n\x05\x43heck\x12&.kessel.inventory.v1beta2.CheckRequest\x1a\'.kessel.inventory.v1beta2.CheckResponse\"$\x82\xd3\xe4\x93\x02\x1e\"\x19/api/kessel/v1beta2/check:\x01*\x12\x8e\x01\n\tCheckSelf\x12*.kessel.inventory.v1beta2.CheckSelfRequest\x1a+.kessel.inventory.v1beta2.CheckSelfResponse\"(\x82\xd3\xe4\x93\x02\"\"\x1d/api/kessel/v1beta2/checkself:\x01*\x12\xa2\x01\n\x0e\x43heckForUpdate\x12/.kessel.inventory.v1beta2.CheckForUpdateRequest\x1a\x30.kessel.inventory.v1beta2.CheckForUpdateResponse\"-\x82\xd3\xe4\x93\x02\'\"\"/api/kessel/v1beta2/checkforupdate:\x01*\x12\x8e\x01\n\tCheckBulk\x12*.kessel.inventory.v1beta2.CheckBulkRequest\x1a+.kessel.inventory.v1beta2.CheckBulkResponse\"(\x82\xd3\xe4\x93\x02\"\"\x1d/api/kessel/v1beta2/checkbulk:\x01*\x12\x9e\x01\n\rCheckSelfBulk\x12..kessel.inventory.v1beta2.CheckSelfBulkRequest\x1a/.kessel.inventory.v1beta2.CheckSelfBulkResponse\",\x82\xd3\xe4\x93\x02&\"!/api/kessel/v1beta2/checkselfbulk:\x01*\x12\x9d\x01\n\x0eReportResource\x12/.kessel.inventory.v1beta2.ReportResourceRequest\x1a\x30.kessel.inventory.v1beta2.ReportResourceResponse\"(\x82\xd3\xe4\x93\x02\"\"\x1d/api/kessel/v1beta2/resources:\x01*\x12\x9d\x01\n\x0e\x44\x65leteResource\x12/.kessel.inventory.v1beta2.DeleteResourceRequest\x1a\x30.kessel.inventory.v1beta2.DeleteResourceResponse\"(\x82\xd3\xe4\x93\x02\"*\x1d/api/kessel/v1beta2/resources:\x01*\x12\x84\x01\n\x13StreamedListObjects\x12\x34.kessel.inventory.v1beta2.StreamedListObjectsRequest\x1a\x35.kessel.inventory.v1beta2.StreamedListObjectsResponse0\x01\x42r\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+descriptor_data = "\n0kessel/inventory/v1beta2/inventory_service.proto\x12\x18kessel.inventory.v1beta2\x1a\x1cgoogle/api/annotations.proto\x1a,kessel/inventory/v1beta2/check_request.proto\x1a-kessel/inventory/v1beta2/check_response.proto\x1a\x37kessel/inventory/v1beta2/check_for_update_request.proto\x1a\x38kessel/inventory/v1beta2/check_for_update_response.proto\x1a\x36kessel/inventory/v1beta2/report_resource_request.proto\x1a\x37kessel/inventory/v1beta2/report_resource_response.proto\x1a\x36kessel/inventory/v1beta2/delete_resource_request.proto\x1a\x37kessel/inventory/v1beta2/delete_resource_response.proto\x1a<kessel/inventory/v1beta2/streamed_list_objects_request.proto\x1a=kessel/inventory/v1beta2/streamed_list_objects_response.proto\x1a=kessel/inventory/v1beta2/streamed_list_subjects_request.proto\x1a>kessel/inventory/v1beta2/streamed_list_subjects_response.proto\x1a\x31kessel/inventory/v1beta2/check_bulk_request.proto\x1a\x32kessel/inventory/v1beta2/check_bulk_response.proto\x1a\x31kessel/inventory/v1beta2/check_self_request.proto\x1a\x32kessel/inventory/v1beta2/check_self_response.proto\x1a\x36kessel/inventory/v1beta2/check_self_bulk_request.proto\x1a\x37kessel/inventory/v1beta2/check_self_bulk_response.proto\x1a<kessel/inventory/v1beta2/check_for_update_bulk_request.proto\x1a=kessel/inventory/v1beta2/check_for_update_bulk_response.proto2\x86\x0c\n\x16KesselInventoryService\x12~\n\x05\x43heck\x12&.kessel.inventory.v1beta2.CheckRequest\x1a\'.kessel.inventory.v1beta2.CheckResponse\"$\x82\xd3\xe4\x93\x02\x1e\"\x19/api/kessel/v1beta2/check:\x01*\x12\x8e\x01\n\tCheckSelf\x12*.kessel.inventory.v1beta2.CheckSelfRequest\x1a+.kessel.inventory.v1beta2.CheckSelfResponse\"(\x82\xd3\xe4\x93\x02\"\"\x1d/api/kessel/v1beta2/checkself:\x01*\x12\xa2\x01\n\x0e\x43heckForUpdate\x12/.kessel.inventory.v1beta2.CheckForUpdateRequest\x1a\x30.kessel.inventory.v1beta2.CheckForUpdateResponse\"-\x82\xd3\xe4\x93\x02\'\"\"/api/kessel/v1beta2/checkforupdate:\x01*\x12\xb2\x01\n\x12\x43heckForUpdateBulk\x12\x33.kessel.inventory.v1beta2.CheckForUpdateBulkRequest\x1a\x34.kessel.inventory.v1beta2.CheckForUpdateBulkResponse\"1\x82\xd3\xe4\x93\x02+\"&/api/kessel/v1beta2/checkforupdatebulk:\x01*\x12\x8e\x01\n\tCheckBulk\x12*.kessel.inventory.v1beta2.CheckBulkRequest\x1a+.kessel.inventory.v1beta2.CheckBulkResponse\"(\x82\xd3\xe4\x93\x02\"\"\x1d/api/kessel/v1beta2/checkbulk:\x01*\x12\x9e\x01\n\rCheckSelfBulk\x12..kessel.inventory.v1beta2.CheckSelfBulkRequest\x1a/.kessel.inventory.v1beta2.CheckSelfBulkResponse\",\x82\xd3\xe4\x93\x02&\"!/api/kessel/v1beta2/checkselfbulk:\x01*\x12\x9d\x01\n\x0eReportResource\x12/.kessel.inventory.v1beta2.ReportResourceRequest\x1a\x30.kessel.inventory.v1beta2.ReportResourceResponse\"(\x82\xd3\xe4\x93\x02\"\"\x1d/api/kessel/v1beta2/resources:\x01*\x12\x9d\x01\n\x0e\x44\x65leteResource\x12/.kessel.inventory.v1beta2.DeleteResourceRequest\x1a\x30.kessel.inventory.v1beta2.DeleteResourceResponse\"(\x82\xd3\xe4\x93\x02\"*\x1d/api/kessel/v1beta2/resources:\x01*\x12\x84\x01\n\x13StreamedListObjects\x12\x34.kessel.inventory.v1beta2.StreamedListObjectsRequest\x1a\x35.kessel.inventory.v1beta2.StreamedListObjectsResponse0\x01\x12\x87\x01\n\x14StreamedListSubjects\x12\x35.kessel.inventory.v1beta2.StreamedListSubjectsRequest\x1a\x36.kessel.inventory.v1beta2.StreamedListSubjectsResponse0\x01\x42r\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
 
 pool = ::Google::Protobuf::DescriptorPool.generated_pool
 pool.add_serialized_file(descriptor_data)

data/lib/kessel/inventory/v1beta2/inventory_service_services_pb.rb

@@ -48,6 +48,14 @@ module Kessel
           # It is intended to be used just prior to sensitive operation (e.g., update, delete)
           # which depend on the current state of the relationship.
           rpc :CheckForUpdate, ::Kessel::Inventory::V1beta2::CheckForUpdateRequest, ::Kessel::Inventory::V1beta2::CheckForUpdateResponse
+          # Performs bulk strongly consistent "check for update" permission checks.
+          #
+          # This API is more efficient than making individual CheckForUpdate calls when verifying
+          # update permissions for multiple resource-subject-relation combinations. Each item
+          # is evaluated with strong consistency (same semantics as CheckForUpdate).
+          #
+          # Common use cases include batch pre-authorization before bulk update or delete operations.
+          rpc :CheckForUpdateBulk, ::Kessel::Inventory::V1beta2::CheckForUpdateBulkRequest, ::Kessel::Inventory::V1beta2::CheckForUpdateBulkResponse
           # Performs bulk permission checks for multiple resource-subject-relation combinations.
           #
           # This API is more efficient than making individual Check calls when verifying permissions
@@ -124,6 +132,17 @@ module Kessel
           #
           # Pagination and consistency controls allow fine-tuned performance and data freshness.
           rpc :StreamedListObjects, ::Kessel::Inventory::V1beta2::StreamedListObjectsRequest, stream(::Kessel::Inventory::V1beta2::StreamedListObjectsResponse)
+          # Streams a list of subjects that have the specified relation to a resource.
+          #
+          # This relationship query answers the question:
+          # "Which subjects of type *X* have relation *Y* to resource *Z*?"
+          #
+          # It is often used for access auditing, troubleshooting permissions, or
+          # displaying lists of users/principals with specific access to a resource.
+          # The result is streamed incrementally to support large datasets.
+          #
+          # Pagination and consistency controls allow fine-tuned performance and data freshness.
+          rpc :StreamedListSubjects, ::Kessel::Inventory::V1beta2::StreamedListSubjectsRequest, stream(::Kessel::Inventory::V1beta2::StreamedListSubjectsResponse)
         end
 
         Stub = Service.rpc_stub_class

data/lib/kessel/inventory/v1beta2/streamed_list_subjects_request_pb.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/streamed_list_subjects_request.proto
+
+require 'google/protobuf'
+
+require 'buf/validate/validate_pb'
+require 'kessel/inventory/v1beta2/resource_reference_pb'
+require 'kessel/inventory/v1beta2/representation_type_pb'
+require 'kessel/inventory/v1beta2/request_pagination_pb'
+require 'kessel/inventory/v1beta2/consistency_pb'
+
+
+descriptor_data = "\n=kessel/inventory/v1beta2/streamed_list_subjects_request.proto\x12\x18kessel.inventory.v1beta2\x1a\x1b\x62uf/validate/validate.proto\x1a\x31kessel/inventory/v1beta2/resource_reference.proto\x1a\x32kessel/inventory/v1beta2/representation_type.proto\x1a\x31kessel/inventory/v1beta2/request_pagination.proto\x1a*kessel/inventory/v1beta2/consistency.proto\"\xf0\x03\n\x1bStreamedListSubjectsRequest\x12O\n\x08resource\x18\x01 \x01(\x0b\x32+.kessel.inventory.v1beta2.ResourceReferenceB\x06\xbaH\x03\xc8\x01\x01R\x08resource\x12#\n\x08relation\x18\x02 \x01(\tB\x07\xbaH\x04r\x02\x10\x01R\x08relation\x12W\n\x0csubject_type\x18\x03 \x01(\x0b\x32,.kessel.inventory.v1beta2.RepresentationTypeB\x06\xbaH\x03\xc8\x01\x01R\x0bsubjectType\x12.\n\x10subject_relation\x18\x04 \x01(\tH\x00R\x0fsubjectRelation\x88\x01\x01\x12P\n\npagination\x18\x05 \x01(\x0b\x32+.kessel.inventory.v1beta2.RequestPaginationH\x01R\npagination\x88\x01\x01\x12L\n\x0b\x63onsistency\x18\x06 \x01(\x0b\x32%.kessel.inventory.v1beta2.ConsistencyH\x02R\x0b\x63onsistency\x88\x01\x01\x42\x13\n\x11_subject_relationB\r\n\x0b_paginationB\x0e\n\x0c_consistencyBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      StreamedListSubjectsRequest = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.StreamedListSubjectsRequest").msgclass
+    end
+  end
+end

data/lib/kessel/inventory/v1beta2/streamed_list_subjects_response_pb.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+# Generated by the protocol buffer compiler.  DO NOT EDIT!
+# source: kessel/inventory/v1beta2/streamed_list_subjects_response.proto
+
+require 'google/protobuf'
+
+require 'kessel/inventory/v1beta2/subject_reference_pb'
+require 'kessel/inventory/v1beta2/response_pagination_pb'
+require 'kessel/inventory/v1beta2/consistency_token_pb'
+
+
+descriptor_data = "\n>kessel/inventory/v1beta2/streamed_list_subjects_response.proto\x12\x18kessel.inventory.v1beta2\x1a\x30kessel/inventory/v1beta2/subject_reference.proto\x1a\x32kessel/inventory/v1beta2/response_pagination.proto\x1a\x30kessel/inventory/v1beta2/consistency_token.proto\"\x8b\x02\n\x1cStreamedListSubjectsResponse\x12\x44\n\x07subject\x18\x01 \x01(\x0b\x32*.kessel.inventory.v1beta2.SubjectReferenceR\x07subject\x12L\n\npagination\x18\x02 \x01(\x0b\x32,.kessel.inventory.v1beta2.ResponsePaginationR\npagination\x12W\n\x11\x63onsistency_token\x18\x03 \x01(\x0b\x32*.kessel.inventory.v1beta2.ConsistencyTokenR\x10\x63onsistencyTokenBr\n(org.project_kessel.api.inventory.v1beta2P\x01ZDgithub.com/project-kessel/inventory-api/api/kessel/inventory/v1beta2b\x06proto3"
+
+pool = ::Google::Protobuf::DescriptorPool.generated_pool
+pool.add_serialized_file(descriptor_data)
+
+module Kessel
+  module Inventory
+    module V1beta2
+      StreamedListSubjectsResponse = ::Google::Protobuf::DescriptorPool.generated_pool.lookup("kessel.inventory.v1beta2.StreamedListSubjectsResponse").msgclass
+    end
+  end
+end

data/lib/kessel/version.rb

@@ -2,6 +2,6 @@
 
 module Kessel
   module Inventory
-    VERSION = '1.7.0'
+    VERSION = '1.9.0'
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kessel-sdk
 version: !ruby/object:Gem::Version
-  version: 1.7.0
+  version: 1.9.0
 platform: ruby
 authors:
 - Project Kessel
@@ -207,6 +207,7 @@ files:
 - lib/google/rpc/status_pb.rb
 - lib/kessel-sdk.rb
 - lib/kessel/auth.rb
+- lib/kessel/console.rb
 - lib/kessel/grpc.rb
 - lib/kessel/inventory.rb
 - lib/kessel/inventory/v1.rb
@@ -238,6 +239,8 @@ files:
 - lib/kessel/inventory/v1beta2/allowed_pb.rb
 - lib/kessel/inventory/v1beta2/check_bulk_request_pb.rb
 - lib/kessel/inventory/v1beta2/check_bulk_response_pb.rb
+- lib/kessel/inventory/v1beta2/check_for_update_bulk_request_pb.rb
+- lib/kessel/inventory/v1beta2/check_for_update_bulk_response_pb.rb
 - lib/kessel/inventory/v1beta2/check_for_update_request_pb.rb
 - lib/kessel/inventory/v1beta2/check_for_update_response_pb.rb
 - lib/kessel/inventory/v1beta2/check_request_pb.rb
@@ -263,6 +266,8 @@ files:
 - lib/kessel/inventory/v1beta2/response_pagination_pb.rb
 - lib/kessel/inventory/v1beta2/streamed_list_objects_request_pb.rb
 - lib/kessel/inventory/v1beta2/streamed_list_objects_response_pb.rb
+- lib/kessel/inventory/v1beta2/streamed_list_subjects_request_pb.rb
+- lib/kessel/inventory/v1beta2/streamed_list_subjects_response_pb.rb
 - lib/kessel/inventory/v1beta2/subject_reference_pb.rb
 - lib/kessel/inventory/v1beta2/write_visibility_pb.rb
 - lib/kessel/rbac/v2.rb