bindan 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77be6a8a1a9d6b820162f7314d2059a3d30913d54df5bac04f97715f78ccbbf7
-  data.tar.gz: fbc74c7696fbdc82e1dfcbfd1cb19ef772173af876796b738c68a338e50e8129
+  metadata.gz: b9be963a07d9adaf6952ec6a57c47ee853e20e601608e5e8d15bdbd9b23ab8b9
+  data.tar.gz: 4a23535e819cee5eea21bf664df8c25ab4ea7dc4fa9714e814a2b9e0153d4bb7
 SHA512:
-  metadata.gz: f486ad2603b6116a4ec212d0ac297e3ba86c2b2d9cd3269f2e5a9c64f7ab4c92d2cdd24480c3b4056ffa31a6e552ba7a001651089986a756cb8e70dd39bcb562
-  data.tar.gz: 626eb96b617d2b5cafe34102ce68f87b73160fcf3b019ab23b46c3b634b7539c5211e075bcfedef86df9fba78a9f0089c007304aa117888bdd4d066a7e75a425
+  metadata.gz: 41ff4d4d2d7c3467ee888a5c4b116ac47e7b2bb19764e2026b7d8c797f10fed4c7470cacfd663771c47dc5cfff28602427080872434f2bd269e80c3d7f4952f4
+  data.tar.gz: 271b943d0837381c9c11dd9169771116c47cdda6caad9c0d51c7d91e2c95c1a4d06e51a97e53e3adfd1d1cc1f452949054511caa1ed34415b36404587a1eac6e

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 ## [Unreleased]
 
+## [0.1.2] - 2026-11-12
+
+### Changed
+
+- Separate Docker-free unit tests from emulator-backed integration tests.
+- Manage GCS and Firestore emulators with Docker Compose. CI starts and stops the services; local integration tests use externally started services.
+- Clear Firestore test data between cases instead of restarting the emulator for each test.
+- Extract Firestore document path resolution without changing lookup behavior.
+
+### Fixed
+
+- Correct the multiple-Provider README example and clarify Storage bucket names and Firestore collection paths.
+- Restore Cloud Storage integration coverage in CI and constrain development dependencies for Ruby 3.0 compatibility.
+
+### Development compatibility
+
+- Remove `bin/emulator` and controller startup/shutdown APIs. Use `docker compose up` / `down` instead; host Java and Google Cloud CLI are no longer required. Firestore import/export is no longer supported by the development tooling.
+
+## [0.1.1] - 2025-08-07
+
+- add Class-extend use
+
 ## [0.1.0] - 2025-08-03
 
 - Initial release

data/README.md

@@ -82,14 +82,14 @@ and
 
 ```ruby
 require "bindan"
-require "google/client/storage"
-require "google/client/firestore"
+require "google/cloud/storage"
+require "google/cloud/firestore"
 
 # Define your configuration providers
 providers = {
   env: Bindan::Provider::Envvar.new,
-  storage: Bindan::Provider::Storage.new(bucket: "my-config-bucket"),
-  firestore: Bindan::Provider::Firestore.new(collection: "app-settings")
+  storage: Bindan::Provider::Storage.new("config-bucket", project_id: "my-project"),
+  firestore: Bindan::Provider::Firestore.new("app-settings-collection", project_id: "my-project")
 }
 
 # Configure Bindan
@@ -108,24 +108,24 @@ puts config.feature_flags # => (Value loaded from Firestore)
 
 In the `configure` block, you define how each configuration key is mapped to a provider. The provider name is `providers` Hash key.
 
+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.
+
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+After checking out the repo, run `bin/setup` to install development dependencies and pull the emulator images. It does not start the containers.
+
+```bash
+bin/setup
+```
+
+You can also run `bin/console` for an interactive prompt that will allow you to experiment.
 
 ### Prerequisites for Development
 
-This gem is designed to interacts with Google Cloud services as a first-class citizen. For local development and testing, it uses emulators. Please install the following tools:
+The development environment includes the following tools for running heavy integration tests locally:
 
-1.  **Google Cloud CLI:** [Installation the gcloud CLI](https://cloud.google.com/sdk/docs/install)
-2.  **Docker:** [Get Docker](https://docs.docker.com/get-docker/)
-3.  **Firestore Emulator:**
-    ```bash
-    gcloud components install cloud-firestore-emulator
-    ```
-4.  **fake-gcs-server:**
-    ```bash
-    docker pull fsouza/fake-gcs-server
-    ```
+1.  **Docker with Docker Compose:** [Get Docker](https://docs.docker.com/get-docker/), with its daemon running.
+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`.
 
 ### Custom Provider
 
@@ -141,12 +141,33 @@ end
 
 ### Running Tests
 
-The test suite is configured to automatically start the emulators (including `fake-gcs-server` via Docker), run the tests against them, and shut them down. Simply run:
+Use the lightweight unit tests during normal development. They do not start emulators:
 
 ```bash
 bundle exec rake spec
 ```
 
+Run the heavy integration tests locally when verifying Provider behavior against the real SDKs and emulators. Start the containers explicitly before running the suite:
+
+```bash
+docker compose up --detach --wait
+bundle exec rake spec:integration
+```
+
+The tests wait for readiness but never start or stop containers. Stop them yourself when no longer needed:
+
+```bash
+docker compose down
+```
+
+CI runs both suites and manages Compose startup, logs and cleanup in the workflow, including cleanup after failures.
+
+Integration tests run serially against Storage on `127.0.0.1:4443` and Firestore on
+`127.0.0.1:8080`. Each Firestore case clears the `bindan-test` project's default
+database before seeding data. Use these emulators for disposable test data only.
+The Firestore controller waits for an SDK request to succeed, not merely a TCP
+connection. The suite does not import or export Firestore data.
+
 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).
 
 ## Contributing

data/Rakefile

@@ -5,7 +5,13 @@ require "minitest/test_task"
 
 Minitest::TestTask.create(:spec) do |t|
   t.libs << "spec"
-  t.test_globs = "spec/**/*_spec.rb"
+  t.test_globs = Dir.glob("spec/**/*_spec.rb").reject { |path| path.start_with?("spec/integration/") }
+  t.warning = false
+end
+
+Minitest::TestTask.create("spec:integration") do |t|
+  t.libs << "spec"
+  t.test_globs = "spec/integration/**/*_spec.rb"
   t.warning = false
 end
 

data/compose.yml

@@ -3,10 +3,24 @@ services:
     image: fsouza/fake-gcs-server:latest
     command: -scheme http -port 4443 -host 0.0.0.0
     ports:
-      - "4443:4443"
+      - "127.0.0.1:4443:4443"
+    volumes:
+      - "./spec/support/storage:/data/-config:ro"
     healthcheck:
       # The fake-gcs-server is ready when we can query the bucket list endpoint.
-      test: ["CMD", "curl", "-f", "http://localhost:4443/storage/v1/b"]
+      test: ["CMD", "wget", "-q", "-O", "/dev/null", "http://127.0.0.1:4443/storage/v1/b"]
       interval: 1s
       timeout: 5s
       retries: 20
+  firestore:
+    image: gcr.io/google.com/cloudsdktool/google-cloud-cli:emulators
+    command:
+      - gcloud
+      - emulators
+      - firestore
+      - start
+      - --host-port=0.0.0.0:8080
+      - --database-mode=firestore-native
+      - --edition=standard
+    ports:
+      - "127.0.0.1:8080:8080"

data/lib/bindan/emulators/firestore_controller.rb

@@ -1,151 +1,121 @@
 require_relative "../error"
-require "fileutils"
-require "open3"
-require "socket"
+require "net/http"
 require "timeout"
-require "uri"
 
 module Bindan
   module Emulator
     #
-    # Represents and controls a single instance of the Google Cloud Firestore emulator process.
-    # This class encapsulates the logic for starting, stopping, and waiting for the emulator,
-    # separating process management from the test execution flow.
+    # Represents and controls a single instance of the Google Cloud Firestore emulator service.
+    # This class checks readiness and clears test data without managing containers.
     #
     class FirestoreController
-      WAIT_TIMEOUT = 15 # seconds
+      WAIT_TIMEOUT = 60 # seconds
       INITIAL_BACKOFF_KEY_SEC = 0.1 # seconds
       BACKOFF_MULTIPLIER = 1.5
 
-      class << self
-        #
-        # @return [Array<String, Integer>]
-        #
-        def host_and_port(host = nil, port = nil)
-          host, port = ENV["FIRESTORE_EMULATOR_HOST"].to_s.split(":") if ENV["FIRESTORE_EMULATOR_HOST"]
+      class Error < StandardError; end
 
-          host ||= ENV["CI"] ? "0.0.0.0" : "localhost"
-          port ||= 8080
+      attr_reader :project_id
 
-          [host, port]
-        end
-
-        #
-        # Initiates the emulator process and returns a new instance.
-        #
-        # @param [String] import
-        # @param [String] export
-        # @param [String] host
-        # @param [Integer] port
-        # @param [bool] close_io
-        # @raise [Errno]
-        # @return [FirestoreEmulatorController] An instance to manage the emulator lifecycle.
-        #
-        def start(import: nil, export: nil, host: nil, port: nil, close_io: true)
-          host, port = host_and_port(host, port)
-
-          puts " Starting Firestore emulator ..." unless close_io
-          kill_process_if_already_exists(host: host, port: port, with_message: !close_io)
-
-          #
-          # This command is known to launch a background Java process and then exit.
-          # Trying keep process info with process group
-          #
-          cmd = "gcloud emulators firestore start --host-port=#{host}:#{port}"
-          cmd += " --import-data=#{import}" if import
-          cmd += " --export-on-exit=#{export}" if export
-          opts = close_io ? {out: "/dev/null", err: "/dev/null"} : {}
-          pid = Process.spawn(*cmd, pgroup: true, **opts) # steep:ignore
-
-          puts "   Emulator process initiated." unless close_io
-          new(pid, host, port)
-        end
-
-        #
-        # kill process group
-        #
-        # @param [Integer] pid
-        # @param [bool] with_message
-        # @return [void]
-        #
-        def stop(pid, with_message: true)
-          puts "\n=> Stopping Firestore emulator..." if with_message
-
-          begin
-            Process.kill("TERM", -pid)
-            Process.wait(-pid)
-          rescue Errno::ESRCH, Errno::ECHILD
-            # Process was already killed or doesn't exist, which is fine.
-          end
-
-          puts "   Emulator process terminated." if with_message
-        end
-
-        #
-        # @param [Integer] host
-        # @param [Integer] port
-        #
-        def kill_process_if_already_exists(host:, port:, with_message: true)
-          TCPSocket.new(host, port).close
-
-          # `lsof -Fg -i:PORT` returns PIDs of the process listening on the port.
-          process_ids, = Open3.capture3(*"lsof -Fg -g -s TCP:LISTEN -i :#{port}".split(" "))
-          process_group = process_ids.lines.map(&:chomp).find { |id| id =~ /^g([0-9]+)/ }
-
-          if process_group
-            id = process_group[1..].to_i # strip first letter
-            puts "   Found emulator process group #{id} on port #{port}. Terminating." if with_message
-            stop(id, with_message: false)
-          end
-        rescue Errno::ECONNREFUSED
-          # noop
-        end
-      end # of class methods
+      #
+      # Select the project used by the integration tests.
+      #
+      def initialize(project_id: "bindan-test")
+        @project_id = project_id
+      end
 
       #
-      # @param [Integer] pid - process group id
+      # @return [String] SDK endpoint (host:port, without an HTTP scheme)
       #
-      def initialize(pid, host, port)
-        @pid = pid
-        @host = host
-        @port = port
+      def endpoint
+        "127.0.0.1:8080"
       end
 
       #
-      # waits to accessable
+      # Wait for an SDK read, retrying false with bounded exponential backoff.
       #
-      # @raise [Timeout::Error] if the emulator does not become available within the configured timeout.
+      # @return [self] after a successful SDK read
+      # @raise [Error] when the overall deadline expires, including during a check
       # @param [number] timeout
       # @param [number] backoff
       # @param [number] multiplier
-      # @return [void]
+      # Failures/interruption propagate; container lifecycle is managed externally.
       #
       def wait_available(timeout: WAIT_TIMEOUT, backoff: INITIAL_BACKOFF_KEY_SEC, multiplier: BACKOFF_MULTIPLIER, with_message: true)
-        last_rescue_error = nil
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        @readiness_error = nil
+        puts "   Waiting for Firestore SDK on #{endpoint}..." if with_message
+        loop do
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          raise Error, "Firestore readiness timed out: #{@readiness_error}" unless remaining > 0
+          return self if Timeout.timeout(remaining) { sdk_ready?([remaining, 2].min) }
+          remaining = deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          sleep [backoff, remaining].min if remaining > 0
+          backoff *= multiplier
+        end
+      rescue Timeout::Error => error
+        raise Error, "Firestore readiness timed out: #{error.message}"
+      end
+
+      #
+      # Clear only this project's default database and wait for DELETE completion.
+      #
+      # @return [self] after HTTP 200, before the next test seeds any data
+      # @raise [Error] for an unsuccessful HTTP status
+      # HTTP/timeout errors propagate; no lifecycle or other-project operations occur.
+      #
+      def clear(timeout: 10)
+        path = "/emulator/v1/projects/#{project_id}/databases/(default)/documents"
+        response = Timeout.timeout(timeout) { delete_documents(path, timeout) }
+        raise Error, "Firestore clear #{project_id} failed: HTTP #{response.code}: #{response.body}" unless response.code == "200"
+        self
+      end
 
-        puts "   Waiting for emulator to be ready on #{@host}:#{@port}..." if with_message
-        count = 1
-        Timeout.timeout(timeout) do
-          loop do
-            TCPSocket.new(@host, @port).close
-            puts "   Emulator is up and listening." if with_message
-            return
-          rescue Errno::ECONNREFUSED, Errno::EADDRNOTAVAIL => e
-            last_rescue_error = e
-            sleep backoff
-            count += 1
-            backoff *= multiplier**count
-          end
+      private
+
+      #
+      # Check a read through the V1 public API, with per-call timeout and no SDK retry.
+      # Keep this lower-level boundary here: high-level doc.get can retry past its timeout.
+      #
+      # @return [Boolean] true on a completed read (a missing document is also valid),
+      #   false only for transient unavailable/deadline errors during startup
+      # Other SDK/configuration errors propagate; no document is written.
+      # Each attempt closes its channel; wait_available also enforces an overall deadline.
+      #
+      def sdk_ready?(timeout)
+        require "google/cloud/firestore/v1"
+        require "grpc"
+        channel = GRPC::Core::Channel.new(endpoint, {}, :this_channel_is_insecure)
+        client = Google::Cloud::Firestore::V1::Firestore::Client.new do |config|
+          config.endpoint = endpoint
+          config.credentials = channel
         end
-      rescue Timeout::Error
-        raise last_rescue_error # steep:ignore
+        database = "projects/#{project_id}/databases/(default)"
+        client.batch_get_documents(
+          {database: database, documents: ["#{database}/documents/bindan-control/readiness"]},
+          {timeout: timeout, retry_policy: {retry_codes: []}}
+        ).each { |_| }
+        @readiness_error = nil
+        true
+      rescue Google::Cloud::UnavailableError, Google::Cloud::DeadlineExceededError => error
+        @readiness_error = error
+        false
+      ensure
+        channel&.close
       end
 
       #
-      # @return [void]
+      # Send clear's local DELETE without environment proxies or redirect following.
+      #
+      # @return [Net::HTTPResponse] the completed response; clear validates its status
+      # Connection and timeout errors propagate to the caller.
       #
-      def stop(with_message: true)
-        self.class.stop(@pid, with_message: with_message)
+      def delete_documents(path, timeout)
+        http = Net::HTTP.new("127.0.0.1", 8080, nil) # Explicitly disable environment proxies.
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+        http.request(Net::HTTP::Delete.new(path))
       end
     end
   end

data/lib/bindan/emulators/gcs_server_controller.rb

@@ -1,89 +1,23 @@
 require_relative "../error"
-require "fileutils"
+require "net/http"
 require "timeout"
-require "open3"
 
 module Bindan
   module Emulator
     class GcsServerController
       class ContainerCannotOpenError < Error; end
 
-      CONTAINER_NAME = "gcs-server"
       WAIT_TIMEOUT = 15 # seconds
       INITIAL_BACKOFF_KEY_SEC = 0.1 # seconds
       BACKOFF_MULTIPLIER = 1.5
 
-      class << self
-        #
-        # @raise [Errno]
-        # @param [String] folder
-        # @param [Integer] [port]
-        # @param [String] [name]
-        # @return [GcsServerController]
-        #
-        def start(folder:, port: 4443, name: CONTAINER_NAME, close_io: true)
-          FileUtils.mkdir_p(folder)
-          unless running?(name: name)
-            opts = close_io ? {out: "/dev/null", err: "/dev/null"} : {}
-            Process.spawn( # steep:ignore
-              *"docker run --rm --name #{name} -p #{port}:4443 -v #{folder}:/data fsouza/fake-gcs-server -scheme http".split(" "),
-              **opts
-            )
-          end
-
-          new(name: name, folder: folder)
-        end
-
-        #
-        # @raise [IOError]
-        # @param [String] name
-        # @return [bool]
-        #
-        def running?(name:)
-          _stdin, stdout, stderr, = Open3.popen3("docker container list -f name=#{name}")
-
-          begin
-            # container list not only headers
-            stdout.readlines.size > 1
-          rescue IOError => e
-            warn "in #{self}"
-            warn "   " + stderr.read
-            raise ContainerCannotOpenError.new e
-          end
-        end
-
-        #
-        # @param [String] name
-        # @raise [Errno]
-        # @return [void]
-        #
-        def stop(name:)
-          `docker container stop #{name}`
-        end
-      end # of class methods
-
-      #
-      # @param [String] name
-      # @param [String] folder
       #
-      def initialize(name:, folder:)
-        @container_name = name
-        @folder = folder
-      end
-
-      #
-      # @return
-      #
-      def stop
-        self.class.stop(name: @container_name)
-      end
-
-      #
-      # @param [String] name
       # @return [bool]
       #
       def running?
-        self.class.running?(name: @container_name)
+        read_status.code == "200"
+      rescue Errno::ECONNREFUSED, Errno::ECONNRESET, Net::OpenTimeout, Net::ReadTimeout
+        false
       end
 
       #
@@ -93,26 +27,29 @@ module Bindan
       # @param [number] timeout
       # @param [number] backoff
       # @param [number] multiplier
-      # @return [void]
+      # @return [self]
       #
       def wait_available(timeout: WAIT_TIMEOUT, backoff: INITIAL_BACKOFF_KEY_SEC, multiplier: BACKOFF_MULTIPLIER)
-        last_rescued_error = nil
-
-        count = 1
         Timeout.timeout(timeout) do
           loop do
-            if running?
-              return
-            end
-          rescue ContainerCannotOpenError => e
-            last_rescued_error = e
+            return self if running?
             sleep backoff
-            count += 1
-            backoff *= multiplier**count
+            backoff *= multiplier
           end
         end
       rescue Timeout::Error
-        raise last_rescued_error # steep:ignore
+        raise ContainerCannotOpenError, "Storage readiness timed out"
+      end
+
+      private
+
+      # Query the published loopback endpoint without environment proxies.
+      # @return [Net::HTTPResponse] completed response; connection errors propagate
+      def read_status
+        http = Net::HTTP.new("127.0.0.1", 4443, nil)
+        http.open_timeout = 2
+        http.read_timeout = 2
+        http.get("/storage/v1/b")
       end
     end
   end

data/lib/bindan/providers/firestore.rb

@@ -33,7 +33,20 @@ module Bindan
       class ColOrDocNotExist < Error; end
 
       #
-      # @param [String] collection
+      # 1. Supply collection when registering the provider to avoid repeating it
+      #    on each document lookup.
+      # 2. Omit collection to access multiple collections through one provider.
+      #    Each lookup must then explicitly supply a full document path
+      #    (collection/document).
+      #
+      # Path examples (collection, key -> document path):
+      # - "app-settings", "flags"       -> "app-settings/flags"
+      # - omitted, "app-settings/flags" -> "app-settings/flags"
+      # - omitted, "maintenance/status" -> "maintenance/status"
+      # - "app-settings", "other/flags" -> "app-settings/other/flags" (invalid)
+      # - omitted, "flags"              -> "/flags" (invalid)
+      #
+      # @param [String, nil] collection fixed collection path, or nil for full-path keys
       # @param [bool] raise_error
       # @param [Google::Cloud::Firestore] sdk
       #
@@ -61,19 +74,25 @@ module Bindan
         @_firestore.doc(path).create(doc)
       end
 
+      #
+      # @param [String] key document ID/path relative to collection, or full path if omitted
+      # @return [String]
+      #
+      def document_path(key)
+        if @collection.nil? && key.include?("/")
+          key
+        else
+          [@collection, key].join("/")
+        end
+      end
+
       #
       # @raise ColOrDocNotExist
-      # @param [String] key
+      # @param [String] key document ID/path relative to collection, or full path if omitted
       # @return [Hash]
       #
       def [](key)
-        doc_path =
-          if @collection.nil? && key.include?("/")
-            key
-          else
-            [@collection, key].join("/")
-          end
-
+        doc_path = document_path(key)
         doc = @_firestore.doc(doc_path).get
 
         if @_options[:raise_error] && !doc.data

data/lib/bindan/providers/storage.rb

@@ -31,9 +31,24 @@ module Bindan
       class FileNotExist < Error; end
 
       #
-      # @param [String] bucket
-      # @param [String] project_id
-      # @param [String] separator
+      # Build the bucket name as [project_id, bucket].join(separator). Keeping
+      # the same bucket suffix across projects makes staging environments easier
+      # to set up: changing project_id selects the corresponding environment's
+      # bucket without changing the suffix or the configuration lookup code.
+      #
+      # Naming examples (bucket argument: "config-bucket"):
+      # - project_id: "my-project", default separator -> "my-project-config-bucket"
+      # - project_id: "staging", default separator    -> "staging-config-bucket"
+      # - project_id omitted, default separator      -> "-config-bucket"
+      # - project_id omitted, separator: ""          -> "config-bucket"
+      # - project_id: "my-project", separator: ""     -> "my-projectconfig-bucket"
+      #
+      # Only an explicitly supplied project_id is used in the bucket name;
+      # a project ID automatically resolved by the SDK is not used.
+      #
+      # @param [String] bucket bucket name suffix, not the full bucket name
+      # @param [String] project_id project ID used for both the SDK and name prefix
+      # @param [String] separator delimiter between project_id and bucket (default: "-")
       # @param [String] credentials
       # @param [Google::Cloud::Storage] sdk
       #

data/lib/bindan/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Bindan
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/sig/bindan/emulators/firestore_controller.rbs

@@ -1,76 +1,47 @@
 module Bindan
   module Emulator
     #
-    # Represents and controls a single instance of the Google Cloud Firestore emulator process.
-    # This class encapsulates the logic for starting, stopping, and waiting for the emulator,
-    # separating process management from the test execution flow.
+    # Represents and controls a single instance of the Google Cloud Firestore emulator service.
+    # This class checks readiness and clears test data without managing containers.
     #
     class FirestoreController
-      @pid: untyped
-
-      @host: untyped
-
-      @port: untyped
-
-      WAIT_TIMEOUT: 15
+      WAIT_TIMEOUT: 60
 
       INITIAL_BACKOFF_KEY_SEC: ::Float
 
       BACKOFF_MULTIPLIER: ::Float
 
-      #
-      # @return [Array<String, Integer>]
-      #
-      def self.host_and_port: (?untyped? host, ?untyped? port) -> ::Array[untyped]
-
-      #
-      # Initiates the emulator process and returns a new instance.
-      #
-      # @param [String] import
-      # @param [String] export
-      # @param [String] host
-      # @param [Integer] port
-      # @param [bool] close_io
-      # @raise [Errno]
-      # @return [FirestoreEmulatorController] An instance to manage the emulator lifecycle.
-      #
-      def self.start: (?import: untyped?, ?export: untyped?, ?host: untyped?, ?port: untyped?, ?close_io: bool) -> untyped
+      class Error < StandardError
+      end
 
-      #
-      # kill process group
-      #
-      # @param [Integer] pid
-      # @param [bool] with_message
-      # @return [void]
-      #
-      def self.stop: (untyped pid, ?with_message: bool) -> untyped
+      @project_id: String
+      @readiness_error: StandardError?
 
-      #
-      # @param [Integer] host
-      # @param [Integer] port
-      #
-      def self.kill_process_if_already_exists: (host: untyped, port: untyped, ?with_message: bool) -> untyped
+      attr_reader project_id: String
 
       #
-      # @param [Integer] pid - process group id
+      # Select the project used by the integration tests.
       #
-      def initialize: (untyped pid, untyped host, untyped port) -> void
+      def initialize: (?project_id: String) -> void
 
       #
-      # waits to accessable
+      # Wait for an SDK read, retrying false with bounded exponential backoff.
       #
-      # @raise [Timeout::Error] if the emulator does not become available within the configured timeout.
+      # @raise [Error] when the overall deadline expires, including during a check
       # @param [number] timeout
       # @param [number] backoff
       # @param [number] multiplier
-      # @return [void]
+      # @return [self] after a successful SDK read
       #
       def wait_available: (?timeout: untyped, ?backoff: untyped, ?multiplier: untyped, ?with_message: bool) -> untyped
 
-      #
-      # @return [void]
-      #
-      def stop: (?with_message: bool) -> untyped
+      def endpoint: () -> String
+      def clear: (?timeout: Numeric) -> FirestoreController
+
+      private
+
+      def sdk_ready?: (Numeric timeout) -> bool
+      def delete_documents: (String path, Numeric timeout) -> Net::HTTPResponse
     end
   end
 end

data/sig/bindan/emulators/gcs_server_controller.rbs

@@ -1,15 +1,9 @@
 module Bindan
   module Emulator
     class GcsServerController
-      @container_name: untyped
-
-      @folder: untyped
-
       class ContainerCannotOpenError < Error
       end
 
-      CONTAINER_NAME: "gcs-server"
-
       WAIT_TIMEOUT: 15
 
       INITIAL_BACKOFF_KEY_SEC: ::Float
@@ -17,55 +11,24 @@ module Bindan
       BACKOFF_MULTIPLIER: ::Float
 
       #
-      # @raise [Errno]
-      # @param [String] folder
-      # @param [Integer] [port]
-      # @param [String] [name]
-      # @return [GcsServerController]
-      #
-      def self.start: (folder: untyped, ?port: ::Integer, ?name: untyped, ?close_io: bool) -> untyped
-
-      #
-      # @raise [IOError]
-      # @param [String] name
       # @return [bool]
       #
-      def self.running?: (name: untyped) -> untyped
-
-      #
-      # @param [String] name
-      # @raise [Errno]
-      # @return [void]
-      #
-      def self.stop: (name: untyped) -> untyped
-
-      #
-      # @param [String] name
-      # @param [String] folder
-      #
-      def initialize: (name: untyped, folder: untyped) -> void
-
-      #
-      # @return
-      #
-      def stop: () -> untyped
-
-      #
-      # @param [String] name
-      # @return [bool]
-      #
-      def running?: () -> untyped
+      def running?: () -> bool
 
       #
       # waits container to be running
       #
-      # @raise [Timeout::Error] if the container does not become available within the configured timeout.
+      # @raise [ContainerCannotOpenError] if the container does not become available within the configured timeout.
       # @param [number] timeout
       # @param [number] backoff
       # @param [number] multiplier
-      # @return [void]
+      # @return [self]
       #
-      def wait_available: (?timeout: untyped, ?backoff: untyped, ?multiplier: untyped) -> untyped
+      def wait_available: (?timeout: Numeric, ?backoff: Numeric, ?multiplier: Numeric) -> GcsServerController
+
+      private
+
+      def read_status: () -> Net::HTTPResponse
     end
   end
 end

data/sig/bindan/providers/firestore.rbs

@@ -36,6 +36,8 @@ module Bindan
       #
       def _prepare: (Hash[String, untyped] pair) -> untyped
 
+      def document_path: (String key) -> String
+
       #
       # @raise ColOrDocNotExist
       # @param [String] key

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: bindan
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - wtnabe
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-08-06 00:00:00.000000000 Z
+date: 2026-11-12 00:00:00.000000000 Z
 dependencies: []
 description: Bindan is a Ruby gem for building single configuration object from various
   sources with providers (that is bundled  Google Cloud Storage and Firestore platform