internetdata 2.8.8 → 2.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6157ddaca572a6fdbec4f07bb91cdcecd4d21bc888a8641e7961411f6e164ea5
-  data.tar.gz: 1fd6bb9d10a79748fb42f053950f3fd4dbe64aaae36b2c9d6c3ab88bf9981594
+  metadata.gz: 783a1de4060fb26d882a1c31aa946d6335be9877da416f0b95712830b5af46b0
+  data.tar.gz: c7eca2b3d6a11c1e5e96b285845458077189645fbdb8ebb28eb63805f5726d75
 SHA512:
-  metadata.gz: 283bda9e8965585d5e110427a3fff75b2e85c437f5f11e2c0eb3fd956adf3d31b8cfb2561ba3c719d339f9e2c11605df54f8c49b67f341e3ba4a4ead8c38474c
-  data.tar.gz: 17ee516cbafe10ee08649833d59813c3e1f81c1650c950c99c17ac5bedfeaa18972d09c234eacdc1a26fb71a00301bfe686602146fda17c498362784bf397e92
+  metadata.gz: '0995aa306107ade8ade8f92244a173dda410f2ea4bb46f4a8d06f0f9c85f3f51e7e8fb5e2661974c411dcdb572440fc71c3111cc84d1e3f5abc6b4c506e01eae'
+  data.tar.gz: 7c032b9d82262035aefe193f3f67dbd82e012771e0a65a55b2bcffea594595a38311cd1c9a27c65e26e2fa24b6ac7ca879555e2a743546355027901601f2f87c

data/README.md

@@ -75,6 +75,14 @@ bytes = client.database.download_bytes('bogon_asn_v1', 'csvgz')
 
 `download_bytes` holds the whole file in memory and the catalog spans seven orders of magnitude, from a few hundred bytes to over 5 GiB, so use `download` for anything you have not checked with `metadata` first.
 
+Each of the three downloads the build that is live unless you name one. A `database.updated` webhook names the build it announces and carries its `sha256`, so a receiver that downloads after the next publish asks for that build to get the file the hash is of:
+
+```ruby
+client.database.download('vpn_ip_v1', 'mmdb', './vpn_ip_v1.mmdb', build: event['data']['build'])
+```
+
+A build is kept 7 days. Past that the call raises `bad_request` with the message `BUILD_GONE`, and downloading without `build:` fetches the live one. A name that is not a build's shape (`20261105.0t53s5`) raises `ArgumentError` before anything is sent.
+
 ### Verifying what you got
 
 ```ruby

data/lib/internetdata/database_api.rb

@@ -73,12 +73,18 @@ module InternetData
     # link authorizes the START of a transfer, so one already running is not
     # interrupted when it lapses.
     #
+    # @param build [String, nil] one build of the database, as a
+    #   `database.updated` webhook names it (`20261105.0t53s5`), so the file is
+    #   the one whose `sha256` the webhook carries. nil or empty, the default, is
+    #   the build that is live. A build is kept 7 days; past that the call raises
+    #   `bad_request` with the message `BUILD_GONE`.
     # @param timeout [Numeric, nil] seconds this attempt may take, for THIS call
     #   only. It bounds the request that MINTS the link, which is an ordinary
     #   JSON call, and says nothing about the transfer you then run with it.
-    def download_url(id, format, timeout: nil)
+    def download_url(id, format, build: nil, timeout: nil)
       check_format!(format)
-      call { redirect_location(id, format, timeout) }
+      build = checked_build(build)
+      call { redirect_location(id, format, build, timeout) }
     end
 
     # Download one database file to `path`, and return the bytes written.
@@ -88,10 +94,13 @@ module InternetData
     # whole database, and a refresh that fails does not destroy the copy already
     # there. Nothing beyond one chunk is ever held in memory, whatever the
     # database weighs.
-    def download(id, format, path)
+    #
+    # @param build [String, nil] one build of the database, as `download_url`
+    #   takes it.
+    def download(id, format, path, build: nil)
       partial = "#{path}.part"
       begin
-        url = download_url(id, format)
+        url = download_url(id, format, build: build)
         written = File.open(partial, 'wb') { |file| transfer(url) { |chunk| file.write(chunk) } }
         File.rename(partial, path)
       rescue StandardError
@@ -108,8 +117,11 @@ module InternetData
     # published database is over 5 GiB. Reach for it at the small end, where the
     # bytes go straight into a parser, and use {#download} for anything you have
     # not measured with {#metadata}.
-    def download_bytes(id, format)
-      url = download_url(id, format)
+    #
+    # @param build [String, nil] one build of the database, as `download_url`
+    #   takes it.
+    def download_bytes(id, format, build: nil)
+      url = download_url(id, format, build: build)
       bytes = String.new(encoding: Encoding::BINARY)
       transfer(url) { |chunk| bytes << chunk }
       bytes
@@ -192,8 +204,17 @@ module InternetData
             "invalid value for \"format\", must be one of #{DatabaseFormat.all_vars}"
     end
 
-    def redirect_location(id, format, timeout)
-      _, status, = @api.download_database_v2_with_http_info(id, format, timeout: timeout)
+    # nil for an empty name, so a value read from an unset setting downloads the
+    # live build.
+    def checked_build(build)
+      return nil if build.nil? || build == ''
+      raise ArgumentError, "build must be a String, not #{build.inspect}" unless build.is_a?(String)
+
+      build
+    end
+
+    def redirect_location(id, format, build, timeout)
+      _, status, = @api.download_database_v2_with_http_info(id, format, build: build, timeout: timeout)
       raise Error.new(:server_error, 'expected a redirect to object storage', status: status)
     rescue ApiError => e
       raise unless e.code == 302

data/lib/internetdata/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module InternetData
-  VERSION = '2.8.8'
+  VERSION = '2.9.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: internetdata
 version: !ruby/object:Gem::Version
-  version: 2.8.8
+  version: 2.9.0
 platform: ruby
 authors:
 - Mslm Dev