screenshotscout 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd3adf5658d59ec5e3c12edc3b0cbe74803d1aee6fbe58786672f2692eb4424d
-  data.tar.gz: e4a6840918f1d719be82c7217fb4fbdbc018a34ab1680ff0e463343222097f5d
+  metadata.gz: 8a670447d2ee6dc8b14865d9161623661cdcd7f8ca0139a5741d61872821d05a
+  data.tar.gz: 9c514cbb7f1f5e0eabc76669c7a83faffbcff07501689749238c6f527dbaa6cb
 SHA512:
-  metadata.gz: c5df1b40ef5da9932e68bf8e5d0a6e8d743c9efa251c59abba8ab9e21af1b5428477dd8154741bc7c2b457f3eb1e256c542b717de40d21d4d2aa49821c9c0b56
-  data.tar.gz: 0335a8cb2be523fdcda670fd44e3a376b45c2f154459594e4e8223dd314c9151977cc6d6a1e3aec2b319e6065ce3e746a0e2f46e74421ee2818e87f0fa89838c
+  metadata.gz: d3606891244c9ec6eb473af8eda9ff48d07b4990ff7263e577920ddf8db12abc787a177bccf8448d3e64f9396640378a2a2e16e0c57f3e78e330d06dbaac5066
+  data.tar.gz: 4e07a85d4ed239504f3629f4d897f93585cbc32c5279898e4819f3b3346c1a6cc4eadecabe5b652504b26d775af5aeb9990dc690f8bbb470a13c51927c159378

data/README.md

@@ -29,7 +29,7 @@ gem install screenshotscout
 store them securely. The access key is required. The secret key is optional and enables
 [signed requests](#signed-requests).
 
-The examples below read `SCREENSHOTSCOUT_ACCESS_KEY` and, when available,
+The examples below read `SCREENSHOTSCOUT_ACCESS_KEY` and, where they sign,
 `SCREENSHOTSCOUT_SECRET_KEY` from environment variables.
 
 ## Capture a screenshot
@@ -40,10 +40,7 @@ the full page and saves the returned image:
 ```ruby
 require "screenshotscout"
 
-client = ScreenshotScout::Client.new(
-  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
-  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
-)
+client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
 response = client.capture(
   "https://example.com",
   ScreenshotScout::CaptureOptions.new(full_page: true)
@@ -64,10 +61,7 @@ image or PDF output:
 ```ruby
 require "screenshotscout"
 
-client = ScreenshotScout::Client.new(
-  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
-  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
-)
+client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
 options = ScreenshotScout::CaptureOptions.new(
   response_type: ScreenshotScout::CaptureResponseType::JSON
 )
@@ -122,8 +116,9 @@ on the [API Keys page](https://screenshotscout.com/app/api-keys).
 
 ## Signed requests
 
-Pass the API key's secret key to sign GET requests, POST requests, and generated capture URLs
-automatically. The secret is used locally and is never transmitted.
+Pass the API key's secret key to sign generated capture URLs and GET requests automatically. The
+secret is used locally and is never transmitted. POST requests can't be signed, so capture with
+`method: CaptureHttpMethod::GET`:
 
 ```ruby
 require "screenshotscout"
@@ -133,7 +128,10 @@ client = ScreenshotScout::Client.new(
   secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY")
 )
 
-response = client.capture("https://example.com")
+response = client.capture(
+  "https://example.com",
+  method: ScreenshotScout::CaptureHttpMethod::GET
+)
 File.binwrite("signed-screenshot.png", response.bytes)
 ```
 
@@ -164,10 +162,7 @@ Use the provided constants for documented values, or pass a string:
 ```ruby
 require "screenshotscout"
 
-client = ScreenshotScout::Client.new(
-  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
-  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
-)
+client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
 options = ScreenshotScout::CaptureOptions.new(
   format: ScreenshotScout::CaptureFormat::WEBP,
   wait_until: ScreenshotScout::CaptureWaitUntil::LOAD
@@ -240,7 +235,6 @@ end
 
 client = ScreenshotScout::Client.new(
   access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
-  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil),
   transport: ApplicationTransport.new(open_timeout: 10, read_timeout: 300)
 )
 
@@ -256,10 +250,7 @@ headers, content type, and body. `APIError` provides the same response details.
 ```ruby
 require "screenshotscout"
 
-client = ScreenshotScout::Client.new(
-  access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"),
-  secret_key: ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
-)
+client = ScreenshotScout::Client.new(access_key: ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY"))
 
 begin
   client.capture("https://example.com")

data/examples/README.md

@@ -14,22 +14,21 @@ From the repository root, install the dependencies:
 bundle install
 ```
 
-Set your access key. Set the optional secret key to use
-[signed requests](../README.md#signed-requests) and signed capture URLs. The secret key is required
-when **Require signed requests** is enabled for the API key.
+Set your access key. To sign the URL that `capture_url.rb` prints, also set the optional secret
+key.
 
 PowerShell:
 
 ```powershell
 $env:SCREENSHOTSCOUT_ACCESS_KEY = "YOUR_ACCESS_KEY"
-$env:SCREENSHOTSCOUT_SECRET_KEY = "YOUR_SECRET_KEY"
+$env:SCREENSHOTSCOUT_SECRET_KEY = "YOUR_SECRET_KEY" # Optional, used by capture_url.rb
 ```
 
 macOS or Linux:
 
 ```shell
 export SCREENSHOTSCOUT_ACCESS_KEY="YOUR_ACCESS_KEY"
-export SCREENSHOTSCOUT_SECRET_KEY="YOUR_SECRET_KEY"
+export SCREENSHOTSCOUT_SECRET_KEY="YOUR_SECRET_KEY" # Optional, used by capture_url.rb
 ```
 
 Run any example:

data/examples/binary.rb

@@ -3,8 +3,7 @@
 require "screenshotscout"
 
 access_key = ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY")
-secret_key = ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
-client = ScreenshotScout::Client.new(access_key: access_key, secret_key: secret_key)
+client = ScreenshotScout::Client.new(access_key: access_key)
 options = ScreenshotScout::CaptureOptions.new(full_page: true)
 response = client.capture("https://example.com", options)
 

data/examples/json.rb

@@ -3,8 +3,7 @@
 require "screenshotscout"
 
 access_key = ENV.fetch("SCREENSHOTSCOUT_ACCESS_KEY")
-secret_key = ENV.fetch("SCREENSHOTSCOUT_SECRET_KEY", nil)
-client = ScreenshotScout::Client.new(access_key: access_key, secret_key: secret_key)
+client = ScreenshotScout::Client.new(access_key: access_key)
 options = ScreenshotScout::CaptureOptions.new(
   response_type: ScreenshotScout::CaptureResponseType::JSON
 )

data/lib/screenshotscout/client.rb

@@ -19,11 +19,13 @@ module ScreenshotScout
       @transport = transport || NetHttpTransport.new
     end
 
-    # Sends one GET or POST request and waits for the final inline response.
+    # Sends one GET or POST request and waits for the final inline response. A client with a secret key
+    # signs GET requests and raises ConfigurationError for POST, because POST requests can't be signed.
     def capture(url, options = nil, method: CaptureHttpMethod::POST)
       serialized = Internal::Serializer.serialize(url, options)
       method = CaptureHttpMethod::POST if method.nil?
       validate_method(method)
+      reject_signed_post(method)
       expected_kind = expected_response_kind(options)
       signature = create_signature(serialized.pairs)
       request = create_request(serialized, method, signature)
@@ -76,6 +78,14 @@ module ScreenshotScout
       )
     end
 
+    def reject_signed_post(method)
+      return if @secret_key.nil? || method != CaptureHttpMethod::POST
+
+      raise ConfigurationError,
+            "POST requests can't be signed. This client has a secret key: send this capture with method GET, " \
+            "or use a client without a secret key and an API key that doesn't require signed requests."
+    end
+
     def create_signature(pairs)
       return nil if @secret_key.nil?
 
@@ -95,14 +105,12 @@ module ScreenshotScout
         url = "#{CAPTURE_ENDPOINT}?#{Internal::Serializer.encode_query(pairs)}"
         TransportRequest.new(method: method, url: url, headers: headers)
       else
-        body = serialized.body.dup
-        body["signature"] = signature unless signature.nil?
         headers["Content-Type"] = "application/json"
         TransportRequest.new(
           method: method,
           url: CAPTURE_ENDPOINT,
           headers: headers,
-          body: Internal::JsonCodec.encode_wire_object(body)
+          body: Internal::JsonCodec.encode_wire_object(serialized.body)
         )
       end
     rescue Error

data/lib/screenshotscout/internal/serializer.rb

@@ -122,7 +122,7 @@ module ScreenshotScout
       end
 
       def encode_query(pairs)
-        pairs.map { |pair| "#{form_encode(pair.name)}=#{form_encode(pair.value)}" }.join("&")
+        pairs.map { |pair| "#{rfc3986_encode(pair.name)}=#{rfc3986_encode(pair.value)}" }.join("&")
       end
 
       def append_repeated(pairs, body, property, wire_name, value)
@@ -199,7 +199,11 @@ module ScreenshotScout
           raise SerializationError.new(message, option: property)
         end
 
-        value.encode(Encoding::UTF_8)
+        string = value.encode(Encoding::UTF_8)
+        # encode doesn't check the bytes of a string that is already tagged as UTF-8.
+        raise Encoding::InvalidByteSequenceError, "invalid byte sequence in UTF-8" unless string.valid_encoding?
+
+        string
       rescue EncodingError => e
         message = if target
                     "The capture target URL must contain valid UTF-8."
@@ -210,19 +214,18 @@ module ScreenshotScout
       end
       private_class_method :string_value
 
-      def form_encode(value)
+      # Percent-encodes UTF-8 bytes, leaving only the RFC 3986 unreserved characters as they are.
+      def rfc3986_encode(value)
         value.bytes.map do |byte|
           if byte.between?(65, 90) || byte.between?(97, 122) ||
-             byte.between?(48, 57) || [42, 45, 46, 95].include?(byte)
+             byte.between?(48, 57) || [45, 46, 95, 126].include?(byte)
             byte.chr
-          elsif byte == 32
-            "+"
           else
             format("%%%02X", byte)
           end
         end.join
       end
-      private_class_method :form_encode
+      private_class_method :rfc3986_encode
     end
   end
 end

data/lib/screenshotscout/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ScreenshotScout
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: screenshotscout
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Oleksii Velykyi