vpndetection 5.2.0 → 5.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 199c0adec648e1556593cb36414f58482fdf2f638f59fad25ca04ee43c0de02c
-  data.tar.gz: f8a7d728594094a46cfcac9ba2306ebd351bc3d80b785eabd1743252a7f6588e
+  metadata.gz: b1a72dc0f5b07ed01b35b61d0cc8a50fda1f1872a18af970690499e0823abc77
+  data.tar.gz: 96a2bbd19642f678ce5f60a8898662a84b27f50cd0d129bc8eaaafaea9fab59b
 SHA512:
-  metadata.gz: b148e272ab33acca1a14b5523c448411d92882a6069ba183522e223077ed5185854feeca378608d68009abaf08ee9a1bcffada932cb42e006455992d07e98eb7
-  data.tar.gz: a42507f48287500895380ded3951be855dcfd24311933efc9a50e79c3c81a230ab32a9f9378d7de9aa33a9778f4e15c5f5d55e94c0f8f8f60bae519cc51f6ece
+  metadata.gz: 7aa1e6b3fe0e4c2b210b9c0a61a28d5d997b794265eb8b40d64d0838834adf850f15854bf267d1b72aafee6af864b6b3c07f2c9b983c39be5d2993ae2c22bb2d
+  data.tar.gz: 42b9392f37d9baffbe6e8aa94d032c6173f1435fa5f0017122c9df8f422bfc6670712487a79617daea87ffd52d225ccc36cccae57cebfe2028f792c08ead26d0

data/README.md

@@ -19,7 +19,7 @@ Or add it to your Gemfile:
 gem 'vpndetection'
 ```
 
-Requires Ruby 3.1 or newer.
+Requires Ruby 3.3 or newer.
 
 ## Usage
 
@@ -160,7 +160,7 @@ client = VPNDetection::Client.new(timeout: 10, retries: 4)
 result = client.lookup('45.83.91.1', timeout: 2, retries: 0)
 ```
 
-`timeout` is in seconds and bounds each attempt, body included, so a call that is retried can take longer in total. It defaults to 30 seconds; before 5.2.0 the default was 10, so pass `timeout: 10` to keep that bound. The client's values are defaults: `lookup`, `lookup_batch`, `my_ip` and `my_entitlement` each take `timeout:` and `retries:` for that call alone, and every `client.oauth` method takes `timeout:`. A database download bounds only its connection with it, because a whole transfer can take minutes.
+`timeout` is in seconds and bounds each attempt, body included, so a call that is retried can take longer in total. It defaults to 30 seconds; before 5.2.0 the default was 10, so pass `timeout: 10` to keep that bound. The client's values are defaults: `lookup`, `lookup_batch`, `my_ip` and `my_entitlement` each take `timeout:` and `retries:` for that call alone, and every `client.oauth` method and every `client.database` call that is not a transfer takes `timeout:` (from 5.3.0). A database download bounds only its connection with it, because a whole transfer can take minutes.
 
 ### Database downloads
 
@@ -177,6 +177,15 @@ bytes = client.database.download_bytes('cdn_ip_v1', 'csvgz')
 
 `download` streams straight to disk, so nothing bigger than a chunk is ever held in memory whatever the database weighs, and it writes through a neighboring `.part` file so a transfer that dies half way leaves no truncated copy behind. `download_url` hands back the time-limited link and follows nothing, for when you want to run the transfer yourself. `download_bytes` holds the whole file in memory, and the catalog runs from `cdn_ip_v1` at 10 KB to `resproxy_ip_90d_v1` at 1.79 GB, so reach for `download` for anything you have not measured.
 
+From 5.3.0, `list`, `metadata`, `checksums`, `downloads` and `download_url` each take `timeout:` in seconds for that call alone, overriding the client's for one attempt of it:
+
+```ruby
+catalog = client.database.list(timeout: 5)
+sums = client.database.checksums(id, 'mmdb', timeout: 5)
+```
+
+`download` and `download_bytes` deliberately take no `timeout:` and raise `ArgumentError` if handed one, rather than accepting it and quietly doing nothing: a transfer runs to gigabytes and minutes, so any bound that suits a JSON call would abandon a healthy download. `download_url` does take one, because minting the link is an ordinary API request - it bounds that request, not whatever you do with the link afterwards.
+
 ### Sign in with OAuth (device flow)
 
 A program running on a person's own machine can let them sign in with their browser and pick one of their API keys, instead of asking them to paste one.

data/lib/vpndetection/database_api.rb

@@ -5,6 +5,12 @@ module VPNDetection
   #
   # Access is granted by contract rather than self-serve, so every method here
   # needs a key carrying the `db.download` scope.
+  #
+  # Every JSON call here takes `timeout:`, in seconds, bounding each ATTEMPT of
+  # that call alone and overriding the bound the client was built with. The two
+  # transfers take none, and are refused it rather than ignoring it: a dataset
+  # runs to gigabytes and minutes, so a bound that suits a JSON call would
+  # abandon a healthy download.
   class DatabaseApi
     def initialize(transport, retries:)
       @transport = transport
@@ -17,13 +23,17 @@ module VPNDetection
     # A license is held against the family, while a download names one version,
     # so the ids {#download}, {#download_bytes}, {#download_url} and {#checksums}
     # take come from each family's `versions`, not from the family itself.
-    def list
-      call { @api.list_databases.databases }
+    #
+    # @param timeout [Numeric, nil] seconds this attempt may take, for THIS call only.
+    def list(timeout: nil)
+      call { @api.list_databases(timeout: timeout).databases }
     end
 
     # What is inside one dataset: schema, samples, row count and sizes.
-    def metadata(id)
-      call { @api.database_metadata(id) }
+    #
+    # @param timeout [Numeric, nil] seconds this attempt may take, for THIS call only.
+    def metadata(id, timeout: nil)
+      call { @api.database_metadata(id, timeout: timeout) }
     end
 
     # The digests for one dataset file.
@@ -31,14 +41,18 @@ module VPNDetection
     # Returns the whole set rather than one algorithm: which digests a dataset
     # publishes is the API's choice, not ours, and the response nests them one
     # level down under `checksums`.
-    def checksums(id, format)
+    #
+    # @param timeout [Numeric, nil] seconds this attempt may take, for THIS call only.
+    def checksums(id, format, timeout: nil)
       check_format!(format)
-      call { @api.database_checksum(id, format).checksums }
+      call { @api.database_checksum(id, format, timeout: timeout).checksums }
     end
 
     # Your organization's recent download attempts, newest first.
-    def downloads(limit: nil)
-      call { @api.list_downloads(limit.nil? ? {} : { limit: limit }).downloads }
+    #
+    # @param timeout [Numeric, nil] seconds this attempt may take, for THIS call only.
+    def downloads(limit: nil, timeout: nil)
+      call { @api.list_downloads(limit: limit, timeout: timeout).downloads }
     end
 
     # The time-limited URL for one dataset file.
@@ -47,9 +61,13 @@ module VPNDetection
     # transfer a file that routinely runs to gigabytes; the link authorizes the
     # START of a transfer, so one already running is not interrupted when it
     # lapses.
-    def download_url(id, format)
+    #
+    # @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)
       check_format!(format)
-      call { redirect_location(id, format) }
+      call { redirect_location(id, format, timeout) }
     end
 
     # Download one dataset file to `path`, and return the bytes written.
@@ -161,8 +179,8 @@ module VPNDetection
     # The 302 is this operation's SUCCESS case, but the generated client treats
     # every non-2xx as a failure, so it arrives as an ApiError carrying the
     # Location header.
-    def redirect_location(id, format)
-      @api.download_database(id, format)
+    def redirect_location(id, format, timeout)
+      @api.download_database(id, format, timeout: timeout)
       raise Error.new(:server_error, 'expected a redirect to object storage')
     rescue ApiError => e
       raise unless e.code == 302

data/lib/vpndetection/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VPNDetection
-  VERSION = '5.2.0'
+  VERSION = '5.4.0'
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: vpndetection
 version: !ruby/object:Gem::Version
-  version: 5.2.0
+  version: 5.4.0
 platform: ruby
 authors:
 - Mslm Dev
@@ -130,7 +130,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '3.1'
+      version: '3.3'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="