bindan 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: b9be963a07d9adaf6952ec6a57c47ee853e20e601608e5e8d15bdbd9b23ab8b9
4
- data.tar.gz: 4a23535e819cee5eea21bf664df8c25ab4ea7dc4fa9714e814a2b9e0153d4bb7
3
+ metadata.gz: 3f8436f7249259c3a94776cb3698fe1afe49446e1b21c7e45a8e2930334602fe
4
+ data.tar.gz: 1241b3b53ba1633c55dd817d59b0300eda7713baccda8611c4bf89488e29b2ff
5
5
  SHA512:
6
- metadata.gz: 41ff4d4d2d7c3467ee888a5c4b116ac47e7b2bb19764e2026b7d8c797f10fed4c7470cacfd663771c47dc5cfff28602427080872434f2bd269e80c3d7f4952f4
7
- data.tar.gz: 271b943d0837381c9c11dd9169771116c47cdda6caad9c0d51c7d91e2c95c1a4d06e51a97e53e3adfd1d1cc1f452949054511caa1ed34415b36404587a1eac6e
6
+ metadata.gz: 92f7df51c973455ec67ef6381b0534f5dd123ca8e336ae24a5cb80f1f9c646222a7db582db41bd31289408251fef0fb3bc23c9fc76d23b6f951380ee1bf8d767
7
+ data.tar.gz: 31499462bfff33ed2f6341db17d5ba9e0dae3215ff70afd1aa5d1045e8f23026097f3083d1e13badefe078496c317ee3cb08ba2d1dc522631f8d39626057f48e
data/CHANGELOG.md CHANGED
@@ -1,5 +1,11 @@
1
1
  ## [Unreleased]
2
2
 
3
+ ## [0.2.0] - 2026-11-13
4
+
5
+ ### Added
6
+
7
+ - Add `Bindan::Provider::SecretManager` to read configuration from Google Cloud Secret Manager.
8
+
3
9
  ## [0.1.2] - 2026-11-12
4
10
 
5
11
  ### Changed
data/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
  [![Gem Version](https://badge.fury.io/rb/bindan.svg)](https://badge.fury.io/rb/bindan)
3
3
  [![CI](https://github.com/wtnabe/bindan/actions/workflows/test.yml/badge.svg)](https://github.com/wtnabe/bindan/actions/workflows/test.yml)
4
4
 
5
- Bindan is a Ruby gem for building single configuration object from various sources with providers (that is bundled Google Cloud Storage and Firestore platform by default). It provides a flexible way to manage application settings, supporting lazy initialization and seamless switching between development (using emulators) and production (eg. actual GCP services) environments.
5
+ Bindan is a Ruby gem for building a single configuration object from various sources with providers (including bundled Google Cloud Storage, Firestore, and Secret Manager providers). It provides a flexible way to manage application settings, supporting lazy initialization and seamless switching between development (using emulators) and production (eg. actual GCP services) environments.
6
6
 
7
7
  ## Features
8
8
 
@@ -11,6 +11,7 @@ Bindan is a Ruby gem for building single configuration object from various sourc
11
11
  - Environment Variables
12
12
  - Google Cloud Storage
13
13
  - Google Cloud Firestore
14
+ - Google Cloud Secret Manager
14
15
  - your custom provider
15
16
 
16
17
  ## Installation
@@ -76,6 +77,7 @@ in Gemfile
76
77
  gem "bindan"
77
78
  gem "google-cloud-storage"
78
79
  gem "google-cloud-firestore"
80
+ gem "google-cloud-secret_manager"
79
81
  ```
80
82
 
81
83
  and
@@ -84,12 +86,14 @@ and
84
86
  require "bindan"
85
87
  require "google/cloud/storage"
86
88
  require "google/cloud/firestore"
89
+ require "google/cloud/secret_manager"
87
90
 
88
91
  # Define your configuration providers
89
92
  providers = {
90
93
  env: Bindan::Provider::Envvar.new,
91
94
  storage: Bindan::Provider::Storage.new("config-bucket", project_id: "my-project"),
92
- firestore: Bindan::Provider::Firestore.new("app-settings-collection", project_id: "my-project")
95
+ firestore: Bindan::Provider::Firestore.new("app-settings-collection", project_id: "my-project"),
96
+ secret: Bindan::Provider::SecretManager.new(project_id: "my-project")
93
97
  }
94
98
 
95
99
  # Configure Bindan
@@ -98,18 +102,26 @@ config = Bindan.configure(providers: providers) do |c, pr|
98
102
  c.database_host = pr.env["DATABASE_HOST"] || "localhost"
99
103
  c.api_key = pr.storage["api_key"]
100
104
  c.feature_flags = pr.firestore["feature_flags_document"]
105
+ c.api_token = pr.secret["api-token"]
101
106
  end
102
107
 
103
108
  # Access your configuration values
104
109
  puts config.database_host # => "localhost" (or value from ENV["DATABASE_HOST"])
105
110
  puts config.api_key # => (Value loaded from Google Cloud Storage)
106
111
  puts config.feature_flags # => (Value loaded from Firestore)
112
+ # Use config.api_token without printing or logging it.
107
113
  ```
108
114
 
109
115
  In the `configure` block, you define how each configuration key is mapped to a provider. The provider name is `providers` Hash key.
110
116
 
111
117
  Replace `my-project` with your Google Cloud project ID. Storage joins `project_id` and the bucket argument with `separator` (default: `"-"`), so this example reads the `api_key` object from the existing `my-project-config-bucket` bucket. Firestore reads the `app-settings-collection/feature_flags_document` document in the same project.
112
118
 
119
+ Secret Manager also accepts an omitted `project_id:`, using `GOOGLE_CLOUD_PROJECT`
120
+ or `GCLOUD_PROJECT` from the environment. An explicit `project_id:` takes precedence.
121
+
122
+ For update and revert precautions and commands, see
123
+ [Secret Manager operations](docs/secret-manager-operations.md).
124
+
113
125
  ## Development
114
126
 
115
127
  After checking out the repo, run `bin/setup` to install development dependencies and pull the emulator images. It does not start the containers.
@@ -125,7 +137,7 @@ You can also run `bin/console` for an interactive prompt that will allow you to
125
137
  The development environment includes the following tools for running heavy integration tests locally:
126
138
 
127
139
  1. **Docker with Docker Compose:** [Get Docker](https://docs.docker.com/get-docker/), with its daemon running.
128
- 2. **Emulators:** `compose.yml` defines fake-gcs-server and the official Google Cloud CLI emulator image. Java and Firestore are provided inside the image; no host Java or Google Cloud CLI installation is required. Storage fixtures are mounted directly from `spec/support/storage`.
140
+ 2. **Emulators:** `compose.yml` defines fake-gcs-server, the official Google Cloud CLI Firestore emulator image, and the unofficial Secret Manager emulator. Java and Firestore are provided inside the image; no host Java or Google Cloud CLI installation is required. Storage fixtures are mounted directly from `spec/support/storage`.
129
141
 
130
142
  ### Custom Provider
131
143
 
@@ -162,11 +174,15 @@ docker compose down
162
174
 
163
175
  CI runs both suites and manages Compose startup, logs and cleanup in the workflow, including cleanup after failures.
164
176
 
165
- Integration tests run serially against Storage on `127.0.0.1:4443` and Firestore on
166
- `127.0.0.1:8080`. Each Firestore case clears the `bindan-test` project's default
167
- database before seeding data. Use these emulators for disposable test data only.
168
- The Firestore controller waits for an SDK request to succeed, not merely a TCP
169
- connection. The suite does not import or export Firestore data.
177
+ Integration tests run serially against Storage on `127.0.0.1:4443`, Firestore on
178
+ `127.0.0.1:8080`, and Secret Manager on `127.0.0.1:9090`. Each Firestore case clears
179
+ the `bindan-test` project's default database before seeding data. Secret Manager
180
+ cases clear secrets in the `bindan-test` project before and after each case.
181
+ Use these emulators for disposable, non-sensitive test data only.
182
+ The Firestore and Secret Manager controllers wait for an SDK request to succeed,
183
+ not merely a TCP connection. The suite does not import or export emulator data.
184
+ To use dummy Storage credentials without local GCP credentials, run
185
+ `CI=true bundle exec rake spec:integration`.
170
186
 
171
187
  To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
172
188
 
data/compose.yml CHANGED
@@ -24,3 +24,13 @@ services:
24
24
  - --edition=standard
25
25
  ports:
26
26
  - "127.0.0.1:8080:8080"
27
+ secret-manager:
28
+ image: ghcr.io/blackwell-systems/gcp-secret-manager-emulator-dual:1.9.0
29
+ environment:
30
+ IAM_MODE: "off"
31
+ GCP_MOCK_LOG_LEVEL: error
32
+ GCP_MOCK_PERSIST: "false"
33
+ tmpfs:
34
+ - /data
35
+ ports:
36
+ - "127.0.0.1:9090:9090"
@@ -0,0 +1,76 @@
1
+ # Secret Manager operations
2
+
3
+ ## Update and revert: what matters
4
+
5
+ - **Update by adding a new version.** This provider reads `latest`, which selects
6
+ the newest created version, not the newest enabled one.
7
+ - **Reverting requires another update.** Record the known-good version before
8
+ making a change. To restore its value, add that value as a new version.
9
+ Disabling or destroying the newest version does not restore the previous one:
10
+ GCP's `latest` still selects the newest created version and reading it fails.
11
+ The emulator may return an older enabled version instead; GCP does not.
12
+ - **Do not expose or accidentally alter the value while updating or reverting.**
13
+ Logs and shell history can retain secrets; added or removed newlines can change
14
+ their meaning. If an update fails or times out, check whether it created a
15
+ version before retrying.
16
+
17
+ ## Manual command examples
18
+
19
+ These examples use Bash and `gcloud`, including Cloud Shell. They modify an
20
+ existing secret; check the account and target before running them, and serialize
21
+ updates to the same secret. The operator needs permissions to
22
+ access/add versions and read version metadata, separate from the application's
23
+ read-only access. Use non-sensitive test data before production use.
24
+
25
+ ```bash
26
+ set +x
27
+ export CLOUDSDK_CORE_LOG_HTTP=false CLOUDSDK_CORE_VERBOSITY=error
28
+ PROJECT_ID="my-project"
29
+ SECRET_ID="api-key"
30
+ gcloud auth list --filter=status:ACTIVE --format='value(account)'
31
+ ```
32
+
33
+ ### Update
34
+
35
+ Prepare a protected file with the exact desired bytes, then add a version.
36
+ Avoid `echo` or embedding secrets in shell commands/history. Record the returned
37
+ version name and the previous known-good version number.
38
+
39
+ ```bash
40
+ gcloud secrets versions add "$SECRET_ID" --project="$PROJECT_ID" \
41
+ --data-file="./api-key.bin" --format='value(name)'
42
+ ```
43
+
44
+ ### Revert
45
+
46
+ Copy a known-good numeric version into a new version, then verify its bytes.
47
+
48
+ ```bash
49
+ (
50
+ set -euo pipefail
51
+ umask 077
52
+ SOURCE_VERSION="1" # Replace with the known-good version number.
53
+ workdir="$(mktemp -d)"
54
+ trap 'rm -rf -- "$workdir"' EXIT
55
+
56
+ gcloud secrets versions access "$SOURCE_VERSION" \
57
+ --secret="$SECRET_ID" --project="$PROJECT_ID" --out-file="$workdir/payload"
58
+ created="$(gcloud secrets versions add "$SECRET_ID" \
59
+ --project="$PROJECT_ID" --data-file="$workdir/payload" --format='value(name)')"
60
+ [[ "$created" =~ /versions/[0-9]+$ ]] || exit 1
61
+ gcloud secrets versions access "${created##*/}" \
62
+ --secret="$SECRET_ID" --project="$PROJECT_ID" --out-file="$workdir/check"
63
+ cmp -s "$workdir/payload" "$workdir/check"
64
+ printf 'Created and verified: %s\n' "$created"
65
+ )
66
+ ```
67
+
68
+ `--out-file` preserves raw bytes, including trailing newlines. Temporary files
69
+ contain plaintext; use a protected environment. Cleanup is not secure erasure.
70
+
71
+ If the command fails or verification reports a mismatch, check which version was
72
+ created and whether its bytes match the intended value before retrying. Do not
73
+ assume a failed command means no version was added.
74
+
75
+ See [version access](https://cloud.google.com/sdk/gcloud/reference/secrets/versions/access)
76
+ and [version addition](https://cloud.google.com/sdk/gcloud/reference/secrets/versions/add).
@@ -0,0 +1,104 @@
1
+ require "google/cloud/secret_manager/v1"
2
+ require "grpc"
3
+ require "logger"
4
+
5
+ module Bindan
6
+ module Emulator
7
+ #
8
+ # Checks readiness and clears local test data without managing containers.
9
+ #
10
+ class SecretManagerController
11
+ WAIT_TIMEOUT = 60 # seconds
12
+
13
+ class Error < StandardError; end
14
+
15
+ attr_reader :project_id, :client
16
+
17
+ #
18
+ # Connect to the local emulator without authentication or payload logging.
19
+ #
20
+ # @param [String] project_id project whose test secrets may be deleted
21
+ #
22
+ def initialize(project_id: "bindan-test")
23
+ @project_id = project_id
24
+ @channel = GRPC::Core::Channel.new(endpoint, {}, :this_channel_is_insecure)
25
+ # @type var retry_codes: Array[Integer]
26
+ retry_codes = []
27
+ @client = Google::Cloud::SecretManager::V1::SecretManagerService::Client.new do |config|
28
+ config.endpoint = endpoint
29
+ config.credentials = @channel
30
+ config.logger = Logger.new(nil)
31
+ config.timeout = 2
32
+ config.retry_policy = {retry_codes: retry_codes}
33
+ end
34
+ end
35
+
36
+ #
37
+ # @return [String] loopback SDK endpoint (host:port, without an HTTP scheme)
38
+ #
39
+ def endpoint
40
+ "127.0.0.1:9090"
41
+ end
42
+
43
+ #
44
+ # Wait for an SDK list request to succeed, retrying transient failures.
45
+ #
46
+ # @param [Numeric] timeout readiness deadline in seconds
47
+ # @return [self] after a successful SDK read
48
+ # @raise [Error] when the readiness deadline expires between attempts
49
+ #
50
+ def wait_available(timeout: WAIT_TIMEOUT)
51
+ deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
52
+ loop do
53
+ remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
54
+ raise Error, "Secret Manager emulator readiness timed out" unless remaining > 0
55
+ return self if sdk_ready?([remaining, 2].min)
56
+ remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
57
+ sleep [0.1, remaining].min if remaining > 0
58
+ end
59
+ end
60
+
61
+ #
62
+ # Delete all secrets and their versions in the selected test project.
63
+ # Collect names before deleting so pagination cannot skip entries.
64
+ #
65
+ # @return [self] after all listed secrets have been deleted
66
+ #
67
+ def clear
68
+ client.list_secrets(parent: "projects/#{project_id}").to_a.each do |secret|
69
+ client.delete_secret(name: secret.name)
70
+ end
71
+ self
72
+ end
73
+
74
+ #
75
+ # Release the shared gRPC channel after the integration run.
76
+ #
77
+ # @return [void]
78
+ #
79
+ def close
80
+ @channel.close
81
+ end
82
+
83
+ private
84
+
85
+ #
86
+ # Probe the list API; only unavailable/deadline errors become false.
87
+ #
88
+ # @param [Numeric] timeout per-request timeout in seconds
89
+ # @return [Boolean] true on success, false on a transient startup failure
90
+ #
91
+ def sdk_ready?(timeout)
92
+ # @type var retry_codes: Array[Integer]
93
+ retry_codes = []
94
+ client.list_secrets(
95
+ {parent: "projects/#{project_id}", page_size: 1},
96
+ {timeout: timeout, retry_policy: {retry_codes: retry_codes}}
97
+ ).each { |_| }
98
+ true
99
+ rescue Google::Cloud::UnavailableError, Google::Cloud::DeadlineExceededError
100
+ false
101
+ end
102
+ end
103
+ end
104
+ end
@@ -0,0 +1,64 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "logger"
4
+ begin
5
+ require "google/cloud/secret_manager"
6
+ require "google/cloud/secret_manager/v1"
7
+ rescue LoadError => e
8
+ warn e
9
+ module Google
10
+ module Cloud
11
+ module SecretManager
12
+ module V1
13
+ module SecretManagerService
14
+ class Client
15
+ def initialize(**kwargs)
16
+ end
17
+
18
+ def access_secret_version(**kwargs)
19
+ Struct.new(:payload).new(Struct.new(:data).new)
20
+ end
21
+ end
22
+ end
23
+ end
24
+ end
25
+ end
26
+ end
27
+ end
28
+
29
+ module Bindan
30
+ module Provider
31
+ class SecretManager
32
+ #
33
+ # Create a reader for global secrets in the supplied or environment project.
34
+ # Discard SDK request/response logs to avoid exposing secret values.
35
+ # Use a null logger: GAPIC treats nil as inheriting the default logger.
36
+ #
37
+ # @param [String, nil] project_id project ID or number; defaults to
38
+ # GOOGLE_CLOUD_PROJECT, then GCLOUD_PROJECT
39
+ # @param [Object] sdk client factory yielding configuration
40
+ # @param [Hash] kwargs SDK client settings (logger is always discarded)
41
+ #
42
+ def initialize(project_id: nil, sdk: ::Google::Cloud::SecretManager::V1::SecretManagerService::Client, **kwargs)
43
+ @project_id = project_id || ENV["GOOGLE_CLOUD_PROJECT"] || ENV["GCLOUD_PROJECT"]
44
+ @_secret_manager = sdk.new do |config|
45
+ kwargs.each { |key, value| config.public_send(:"#{key}=", value) }
46
+ config.logger = Logger.new(nil)
47
+ end
48
+ end
49
+ attr_reader :project_id
50
+
51
+ #
52
+ # Read the latest payload without caching or modifying its bytes.
53
+ #
54
+ # @param [String] key secret ID
55
+ # @return [String] secret payload bytes
56
+ # @raise [Google::Cloud::Error] when the SDK reports a service error
57
+ #
58
+ def [](key)
59
+ name = "projects/#{@project_id}/secrets/#{key}/versions/latest"
60
+ @_secret_manager.access_secret_version(name: name).payload.data
61
+ end
62
+ end
63
+ end
64
+ end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Bindan
4
- VERSION = "0.1.2"
4
+ VERSION = "0.2.0"
5
5
  end
@@ -0,0 +1,49 @@
1
+ module GRPC
2
+ module Core
3
+ class Channel
4
+ def self.new: (String target, Hash[String, untyped] args, Symbol credentials) -> Channel
5
+ def close: () -> void
6
+ end
7
+ end
8
+ end
9
+
10
+ module Google
11
+ module Cloud
12
+ class Error < StandardError
13
+ end
14
+
15
+ class UnavailableError < Error
16
+ end
17
+
18
+ class DeadlineExceededError < Error
19
+ end
20
+ end
21
+ end
22
+
23
+ module Bindan
24
+ module Emulator
25
+ class SecretManagerController
26
+ WAIT_TIMEOUT: 60
27
+
28
+ class Error < StandardError
29
+ end
30
+
31
+ @project_id: String
32
+ @channel: GRPC::Core::Channel
33
+ @client: untyped
34
+
35
+ attr_reader project_id: String
36
+ attr_reader client: untyped
37
+
38
+ def initialize: (?project_id: String) -> void
39
+ def endpoint: () -> String
40
+ def wait_available: (?timeout: Integer | Float) -> SecretManagerController
41
+ def clear: () -> SecretManagerController
42
+ def close: () -> void
43
+
44
+ private
45
+
46
+ def sdk_ready?: (Integer | Float timeout) -> bool
47
+ end
48
+ end
49
+ end
@@ -0,0 +1,28 @@
1
+ module Google
2
+ module Cloud
3
+ module SecretManager
4
+ module V1
5
+ module SecretManagerService
6
+ class Client
7
+ def initialize: (**untyped kwargs) -> void
8
+ def self.new: () { (untyped config) -> void } -> untyped
9
+ def access_secret_version: (**untyped kwargs) -> untyped
10
+ end
11
+ end
12
+ end
13
+ end
14
+ end
15
+ end
16
+
17
+ module Bindan
18
+ module Provider
19
+ class SecretManager
20
+ @project_id: String?
21
+ @_secret_manager: untyped
22
+
23
+ def initialize: (?project_id: String?, ?sdk: untyped, **untyped kwargs) -> void
24
+ attr_reader project_id: String?
25
+ def []: (String key) -> untyped
26
+ end
27
+ end
28
+ end
metadata CHANGED
@@ -1,20 +1,20 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: bindan
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.2
4
+ version: 0.2.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - wtnabe
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-11-12 00:00:00.000000000 Z
11
+ date: 2026-11-14 00:00:00.000000000 Z
12
12
  dependencies: []
13
- description: Bindan is a Ruby gem for building single configuration object from various
14
- sources with providers (that is bundled Google Cloud Storage and Firestore platform
15
- by default). It provides a flexible way to manage application settings, supporting
16
- lazy initialization and seamless switching between development (using emulators)
17
- and production (eg. actual GCP services) environments.
13
+ description: Bindan is a Ruby gem for building a single configuration object from
14
+ various sources with providers (including bundled Google Cloud Storage, Firestore,
15
+ and Secret Manager providers). It provides a flexible way to manage application
16
+ settings, supporting lazy initialization and seamless switching between development
17
+ (using emulators) and production (eg. actual GCP services) environments.
18
18
  email:
19
19
  - 18510+wtnabe@users.noreply.github.com
20
20
  executables: []
@@ -30,13 +30,16 @@ files:
30
30
  - Rakefile
31
31
  - Steepfile
32
32
  - compose.yml
33
+ - docs/secret-manager-operations.md
33
34
  - lib/bindan.rb
34
35
  - lib/bindan/emulators/firestore_controller.rb
35
36
  - lib/bindan/emulators/gcs_server_controller.rb
37
+ - lib/bindan/emulators/secret_manager_controller.rb
36
38
  - lib/bindan/error.rb
37
39
  - lib/bindan/providers.rb
38
40
  - lib/bindan/providers/envvar.rb
39
41
  - lib/bindan/providers/firestore.rb
42
+ - lib/bindan/providers/secret_manager.rb
40
43
  - lib/bindan/providers/storage.rb
41
44
  - lib/bindan/version.rb
42
45
  - rbs_collection.lock.yaml
@@ -44,9 +47,11 @@ files:
44
47
  - sig/bindan.rbs
45
48
  - sig/bindan/emulators/firestore_controller.rbs
46
49
  - sig/bindan/emulators/gcs_server_controller.rbs
50
+ - sig/bindan/emulators/secret_manager_controller.rbs
47
51
  - sig/bindan/error.rbs
48
52
  - sig/bindan/providers/envvar.rbs
49
53
  - sig/bindan/providers/firestore.rbs
54
+ - sig/bindan/providers/secret_manager.rbs
50
55
  - sig/bindan/providers/storage.rbs
51
56
  - sig/bindan/version.rbs
52
57
  homepage: https://github.com/wtnabe/bindan