Class: Cerbos::Hub::Stores::Client

Inherits:
Object
  • Object
show all
Defined in:
lib/cerbos/hub/stores/client.rb

Overview

A client for interacting with policy stores in Cerbos Hub.

Instance Method Summary collapse

Constructor Details

#initialize(client_id:, client_secret:, target: "api.cerbos.cloud:443", grpc_channel_args: {}, grpc_metadata: {}, timeout: nil) ⇒ Client

Create a client for interacting with policy stores in Cerbos Hub.

Parameters:

  • client_id (String) —

    ID of the client credential to authenticate with Cerbos Hub.

  • client_secret (String) —

    secret of the client credential to authenticate with Cerbos Hub.

  • target (String) (defaults to: "api.cerbos.cloud:443") —

    address of the Cerbos Hub server.

  • grpc_channel_args (Hash{String, Symbol => String, Integer}) (defaults to: {}) —

    low-level settings for the gRPC channel (see available keys in the gRPC documentation).

  • grpc_metadata (Hash{String, Symbol => String, Array<String>}) (defaults to: {}) —

    gRPC metadata (a.k.a. HTTP headers) to add to every request to the PDP.

  • timeout (Numeric, nil) (defaults to: nil) —

    timeout for gRPC calls, in seconds (nil to never time out).



16
17
18
19
20
21
22
23
24
25
26
 
# File 'lib/cerbos/hub/stores/client.rb', line 16

def initialize(client_id:, client_secret:, target: "api.cerbos.cloud:443", grpc_channel_args: {}, grpc_metadata: {}, timeout: nil)
  @service = Service.new(
    client_id:,
    client_secret:,
    stub: Protobuf::Cerbos::Cloud::Store::V1::CerbosStoreService::Stub,
    target:,
    grpc_channel_args:,
    grpc_metadata:,
    timeout:
  )
end

Instance Method Details

#get_files(store_id:, files:, grpc_metadata: {}) ⇒ Output::GetFiles

Get file contents from a policy store.

Examples:

client.get_files(store_id: "MWPKEMFX3CK1", files: ["path/to/policy.yaml"])

Parameters:

  • store_id (String) —

    ID of the store from which to get files.

  • files (Array<String>) —

    paths of the files to retrieve.

  • grpc_metadata (Hash{String, Symbol => String, Array<String>}) (defaults to: {}) —

    gRPC metadata (a.k.a. HTTP headers) to add to the request.

Returns:



38
39
40
41
42
43
44
45
46
 
# File 'lib/cerbos/hub/stores/client.rb', line 38

def get_files(store_id:, files:, grpc_metadata: {})
  Error.handle do
    request = Protobuf::Cerbos::Cloud::Store::V1::GetFilesRequest.new(store_id:, files:)

    response = @service.call(:get_files, request, grpc_metadata)

    Output::GetFiles.from_protobuf(response)
  end
end

#list_files(store_id:, filter: nil, grpc_metadata: {}) ⇒ Output::ListFiles

List file paths in a policy store.

Examples:

client.list_files(store_id: "MWPKEMFX3CK1")

Parameters:

  • store_id (String) —

    ID of the store from which to list files.

  • filter (Input::FileFilter, Hash, nil) (defaults to: nil) —

    filter to limit which files are listed.

  • grpc_metadata (Hash{String, Symbol => String, Array<String>}) (defaults to: {}) —

    gRPC metadata (a.k.a. HTTP headers) to add to the request.

Returns:



58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/cerbos/hub/stores/client.rb', line 58

def list_files(store_id:, filter: nil, grpc_metadata: {})
  Error.handle do
    request = Protobuf::Cerbos::Cloud::Store::V1::ListFilesRequest.new(
      store_id:,
      filter: Cerbos::Input.coerce_optional(filter, Input::FileFilter)&.to_protobuf
    )

    response = @service.call(:list_files, request, grpc_metadata)

    Output::ListFiles.from_protobuf(response)
  end
end

#modify_files(store_id:, operations:, condition: nil, change_details: nil, allow_unchanged: false, grpc_metadata: {}) ⇒ Output::ModifyFiles

Modify files in a policy store.

This is a "patch" operation; files that aren't included in the request won't be modified.

Examples:

client.modify_files(
  store_id: "MWPKEMFX3CK1",
  operations: [{add_or_update: {path: "policy.yaml", contents: ::File.binread("path/to/policy.yaml")}}]
)

Parameters:

  • store_id (String) —

    ID of the store in which to modify files.

  • operations (Array<Input::FileOperation, Hash>) —

    modifications to make.

  • condition (Input::FileModificationCondition, Hash, nil) (defaults to: nil) —

    a condition that must be met for the modifications to be made.

  • change_details (Input::ChangeDetails, Hash, nil) (defaults to: nil) —

    metadata describing the change being made.

  • allow_unchanged (Boolean) (defaults to: false) —

    allow modifications that do not change the state of the store. If false (the default), an Error::OperationDiscarded will be thrown if the modifications leave the store unchanged. If true, no error will be thrown and the current store version will be returned.

  • grpc_metadata (Hash{String, Symbol => String, Array<String>}) (defaults to: {}) —

    gRPC metadata (a.k.a. HTTP headers) to add to the request.

Returns:



89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/cerbos/hub/stores/client.rb', line 89

def modify_files(store_id:, operations:, condition: nil, change_details: nil, allow_unchanged: false, grpc_metadata: {})
  Error.handle do
    request = Protobuf::Cerbos::Cloud::Store::V1::ModifyFilesRequest.new(
      store_id:,
      operations: Cerbos::Input.coerce_array(operations, Input::FileOperation).map(&:to_protobuf),
      condition: Cerbos::Input.coerce_optional(condition, Input::FileModificationCondition)&.to_protobuf_modify_files,
      change_details: Cerbos::Input.coerce_optional(change_details, Input::ChangeDetails)&.to_protobuf
    )

    response = @service.call(:modify_files, request, grpc_metadata)

    Output::ModifyFiles.from_protobuf(response)
  end
rescue Error::OperationDiscarded => error
  raise unless allow_unchanged

  Output::ModifyFiles.new(
    new_store_version: error.current_store_version,
    changed: false
  )
end

#replace_files(store_id:, files: nil, zipped_contents: nil, condition: nil, change_details: nil, allow_unchanged: false, grpc_metadata: {}) ⇒ Output::ReplaceFiles

Replace files in a policy store.

This is a "put" operation; files that aren't included in the request will be removed from the store.

Examples:

Upload individual files

client.replace_files(
  store_id: "MWPKEMFX3CK1",
  files: [{path: "policy.yaml", contents: ::File.binread("path/to/policy.yaml")}]
)

Upload zipped files

client.replace_files(
  store_id: "MWPKEMFX3CK1",
  zipped_contents: ::File.binread("path/to/policies.zip")
)

Parameters:

  • store_id (String) —

    ID of the store in which to replace files.

  • files (Array<File, Hash>, nil) (defaults to: nil) —

    files to upload to the store. Mutually exclusive with zipped_contents.

  • zipped_contents (String, nil) (defaults to: nil) —

    binary-encoded string containing zipped files to upload to the store.

  • condition (Input::FileModificationCondition, Hash, nil) (defaults to: nil) —

    a condition that must be met for the replacement to be made.

  • change_details (Input::ChangeDetails, Hash, nil) (defaults to: nil) —

    metadata describing the change being made.

  • allow_unchanged (Boolean) (defaults to: false) —

    allow replacements that do not change the state of the store. If false (the default), an Error::OperationDiscarded will be thrown if the contents match those of the store. If true, no error will be thrown and the current store version will be returned.

  • grpc_metadata (Hash{String, Symbol => String, Array<String>}) (defaults to: {}) —

    gRPC metadata (a.k.a. HTTP headers) to add to the request.

Returns:



136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/cerbos/hub/stores/client.rb', line 136

def replace_files(store_id:, files: nil, zipped_contents: nil, condition: nil, change_details: nil, allow_unchanged: false, grpc_metadata: {})
  Error.handle do
    request = Protobuf::Cerbos::Cloud::Store::V1::ReplaceFilesRequest.new(
      store_id:,
      files: files && Protobuf::Cerbos::Cloud::Store::V1::ReplaceFilesRequest::Files.new(files: files.map { |file| Cerbos::Input.coerce_required(file, File).to_protobuf }),
      zipped_contents:,
      condition: Cerbos::Input.coerce_optional(condition, Input::FileModificationCondition)&.to_protobuf_replace_files,
      change_details: Cerbos::Input.coerce_optional(change_details, Input::ChangeDetails)&.to_protobuf
    )

    response = @service.call(:replace_files, request, grpc_metadata)

    Output::ReplaceFiles.from_protobuf(response)
  end
rescue Error::OperationDiscarded => error
  raise unless allow_unchanged

  Output::ReplaceFiles.new(
    new_store_version: error.current_store_version,
    ignored_files: error.ignored_files,
    changed: false
  )
end