poli-page 0.11.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0caa9c1105af62976da1ba1a5a6ef40ad34386359f1b43cea033976146054d6c
-  data.tar.gz: ed1c09e7c54ab2ee34d9b6286a674c755ef6a1450b53569490be006939c3ae0d
+  metadata.gz: f6e6c0236a43dbf8ecc971781a63e99e6e878f045f4ebf9b9c86f589618f69fc
+  data.tar.gz: d4b0dc1776a2090b1dd57c5623a819048050f1188fcf8ad519a78d2c03ca481e
 SHA512:
-  metadata.gz: 779392d70b3ca9aa042d5e935f5d24d9da8d4eede920f43dfb656907107f924672aa644744a0edceb3950538118d99ff3b8fd24ebef274fa2da27d400dc3b68d
-  data.tar.gz: 0ddcc5b1c996fb19e51c60025a9353412a6f3f198e84d263a3385eff435d659e303828795efb5185067e2bf8383fb88218b56928e640f35d70cecc3046c38e06
+  metadata.gz: 9325ac500f8e8dff0f9049b14214285d877f58b01123fc8dc061fcec54db51329aaa7bc4a771ed56ee94dc987e20a84d88789bb865bb61c2df7089bf4605c259
+  data.tar.gz: 6b97af27df67085ea10b23d334a683a8f85535f454bc51ab122dd2dcb68c996f16d51f7e073f918cf9c595b71eb26b75557decf968830492dae9f4e1f48bfa12

data/CHANGELOG.md

@@ -10,6 +10,84 @@ Breaking releases (minor bumps while on 0.x) are summarized in
 
 ## [Unreleased]
 
+## [0.13.0] - 2026-11-02
+
+Conformance with the Poli Page API contract v0.13.0
+([poli-page/api-contract](https://github.com/poli-page/api-contract)). The
+SDK now shares its major.minor with the Poli Page API, so it moves from 0.11
+to 0.13. See [MIGRATION.md](MIGRATION.md#from-0110-to-0130).
+
+### Added
+
+- `invalid_response`: a 2xx answer whose body is not JSON, from a method that
+  expects JSON (the API call of `render.document`, `render.pdf` and
+  `render.pdf_stream`, `documents.get`, `documents.thumbnails`), raises
+  `PoliPage::InvalidResponseError` with the code `invalid_response`, the
+  message `Invalid response: HTTP <status> body is not JSON`, the real 2xx as
+  `status`, the answer's `x-request-id` as `request_id`, and the JSON
+  parser's error as `cause`. It is never retried, `retryable?` is `false`,
+  and `on_error` fires with it. Such a body usually comes from a proxy or a
+  captive portal between the SDK and the API.
+- `io_error`: `render_to_file` raises `PoliPage::FileWriteError` when it
+  cannot write the file (creating a parent directory, opening, writing or
+  moving it into place). No status, the message
+  `Failed to write PDF: <reason>` with Ruby's own error text, that error as
+  `cause`, never retried.
+- `to_payload` answers `status` 502 for `invalid_response`. The error's own
+  `status` keeps the real 2xx.
+- `scripts/release.sh` and the release workflow check that the API contract
+  pinned for the tests has the release's major.minor (see
+  [RELEASING.md](RELEASING.md)).
+
+### Changed
+
+- **BREAKING**: `Error#to_payload` returns `{ code:, message:, status:,
+  requestId: }`: the `:request_id` key is renamed `:requestId`, the key every
+  Poli Page SDK uses, so every framework integration answers the same JSON
+  body (`"requestId"`). Read `payload[:requestId]` instead of
+  `payload[:request_id]`. The other keys are unchanged.
+- **BREAKING**: a 2xx whose body is not JSON (an empty body included) was
+  `PoliPage::InternalError` (`INTERNAL_ERROR`,
+  `response body was not valid JSON: …`); it is now `invalid_response`
+  (above). A 2xx JSON value that is not an object stays `INTERNAL_ERROR`.
+- **BREAKING**: `render_to_file` failures to write the file are now
+  `io_error`, whatever the error. Before, `EACCES`, `ENOSPC`, `EISDIR`,
+  `ENOENT` and `EROFS` were `PoliPage::InvalidOptionsError`
+  (`invalid_options`, `failed to write to <path>: …`), and any other error
+  (`ENOTDIR`, `EPERM`, `IOError`…) escaped as the raw Ruby exception.
+- `render_to_file` writes to a temporary file in the target's directory and
+  renames it over the target only once the PDF is complete. When anything
+  fails (the render, the download or the write), the target is left as it
+  was: an existing file keeps its content and a missing one is not created
+  (before, a failure deleted the target). The directory and the temporary
+  file are prepared before the render, so a path that cannot be written
+  costs no render. A new file gets the usual mode (`0666` minus the umask);
+  a replaced file keeps its own. When the target is a symbolic link, the file
+  it points to gets the PDF and the link stays a link. An existing target
+  that is not a regular file (a directory, a FIFO, a device, a socket)
+  raises `io_error` with the message
+  `Failed to write PDF: <path>: not a regular file`, and one that is not
+  writable raises `io_error` too; both fail before any render and are not
+  replaced. Because the PDF is renamed into place, `render_to_file` needs
+  write permission on the target's directory, and a replaced file is a new
+  file: it is owned by the user that runs the SDK, and a hard link to the
+  old file keeps the old content.
+- The presigned-URL download is bounded by the client's `timeout:`. For
+  `render.pdf` and `download_pdf` it bounds the whole download, from the
+  connection to the last byte. For `render.pdf_stream` and `render_to_file`
+  it bounds the wait for the first byte of the PDF (connection, answer and
+  first chunk together), then each wait for the next chunk (an idle
+  timeout), so a large PDF read at the caller's pace is not cut off.
+  Before, `timeout:` only bounded each socket operation of the download, so
+  a slow storage could keep `render.pdf` going well past it.
+- A download that outlasts its timeout raises `DOWNLOAD_FAILED` with the
+  message `Failed to download PDF: timeout` (was
+  `Failed to download PDF: network error`). No status, not retryable. A
+  download whose connection closes before the announced `Content-Length`
+  still raises `Failed to download PDF: network error`.
+- A `timeout:` of zero or less makes the download fail at once with the
+  timeout message, as it already made every API call time out.
+
 ## [0.11.0] - 2026-10-30
 
 Conformance with the Poli Page API contract v1.3.0

data/MIGRATION.md

@@ -6,6 +6,80 @@ This file documents breaking changes between releases of `poli-page`
 0.x, a breaking change bumps the minor version; from 1.0 on, only a major
 version does. Every breaking release comes with an entry here.
 
+## From 0.11.0 to 0.13.0
+
+The SDK now shares its major.minor with the Poli Page API, so there is no
+0.12. This release follows the API contract v0.13.0. No method or option is
+renamed; error handling and framework integrations may need a change.
+
+### `to_payload` names its request id `requestId`
+
+`Error#to_payload` returns the body a framework integration answers with,
+and every Poli Page SDK now spells it the same way: exactly the keys
+`code:`, `message:`, `status:` and `requestId:`. Its `:request_id` key is
+renamed `:requestId`; the other keys are unchanged.
+
+```ruby
+# 0.11.0
+payload = e.to_payload
+payload[:request_id]           # => "req_..."
+render json: payload           # answered {"code":…,"request_id":"req_…"}
+
+# 0.13.0
+payload = e.to_payload
+payload[:requestId]            # => "req_..."
+render json: payload           # answers {"code":…,"requestId":"req_…"}
+```
+
+If your integration renamed `request_id` to `requestId` itself, drop the
+rename. Its `:status` is 502 for the new `invalid_response` (below).
+
+### A 2xx whose body is not JSON is `invalid_response`
+
+It was `PoliPage::InternalError` (`INTERNAL_ERROR`,
+`response body was not valid JSON: …`). It is now
+`PoliPage::InvalidResponseError`, code `invalid_response`, message
+`Invalid response: HTTP <status> body is not JSON`, with the real 2xx as
+`status` and the answer's request id. It is not retried.
+
+```ruby
+# 0.11.0
+rescue PoliPage::InternalError => e
+  # a proxy answered instead of the API, if e.status is a 2xx
+
+# 0.13.0
+rescue PoliPage::InvalidResponseError => e
+  # a proxy answered instead of the API; e.status is its 2xx
+```
+
+### `render_to_file` raises `io_error`
+
+A file that cannot be written was `PoliPage::InvalidOptionsError` for
+`EACCES`, `ENOSPC`, `EISDIR`, `ENOENT` and `EROFS`, and the raw Ruby
+exception for anything else; it is now always `PoliPage::FileWriteError`,
+code `io_error`, with the message
+`Failed to write PDF: <reason>` and Ruby's error as `cause`. The target is
+left untouched on any failure: it is no longer deleted when the render
+fails.
+
+```ruby
+# 0.13.0
+rescue PoliPage::FileWriteError => e
+  # disk full, permissions, a missing mount...
+  logger.error(e.cause)
+```
+
+### The PDF download is bounded by `timeout:`
+
+The presigned-URL download now uses the client's `timeout:` (60 s by
+default). `render.pdf` and `download_pdf` bound the whole download, so raise
+`timeout:` if your PDFs take longer than that to download.
+`render.pdf_stream` and `render_to_file` use it as an idle timeout, the wait
+for the first byte of the PDF and each gap between two chunks, and are never cut off for
+their total length. Past the timeout the error is `DOWNLOAD_FAILED` with the
+message `Failed to download PDF: timeout` (was
+`Failed to download PDF: network error`).
+
 ## From 0.10.0 to 0.11.0
 
 The SDK now follows the Poli Page API contract v1.3.0, the same retry policy,

data/README.md

@@ -91,9 +91,18 @@ client.render_to_file(
 )
 ```
 
-`render_to_file` streams the response bytes directly to disk via
+`render_to_file` streams the response bytes to disk via
 `render.pdf_stream` — bounded memory regardless of PDF size. Parent
-directories are created on the fly.
+directories are created on the fly. The PDF goes to a temporary file next
+to the target, renamed over it once complete, so a failed render, download
+or write leaves the target as it was. This needs write permission on the
+target's directory, and a replaced file is a new file (your process owns
+it; a hard link to the old one keeps the old content). A symbolic link is
+followed: the file it points to gets the PDF. A target that is not a
+regular file (a directory, a FIFO, a device) fails before any render with
+`Failed to write PDF: <path>: not a regular file`. A file that cannot be written raises
+`PoliPage::FileWriteError` (code `io_error`, message
+`Failed to write PDF: <reason>`, the Ruby error as `cause`).
 
 ### Try it locally — runnable demo
 
@@ -170,7 +179,11 @@ client.documents.delete(doc.document_id)
 
 The presigned URL has a 15-minute TTL. If `download_pdf` raises
 `PoliPage::DownloadError` with `status: 403` from S3, call
-`documents.get(id)` to refresh and retry.
+`documents.get(id)` to refresh and retry. The client's `timeout:` also
+bounds the download: the whole download for `download_pdf` and
+`render.pdf`, and the wait for the first byte, then each wait for the next
+chunk, for `render.pdf_stream` and `render_to_file`. Past it, `DownloadError` has the message
+`Failed to download PDF: timeout`.
 
 ## Authentication & environments
 
@@ -222,7 +235,7 @@ through as a `Bearer` token and does not check its format.
 | `base_url:`   | `String`                   | `"https://api.poli.page"`  | API base URL                                 |
 | `max_retries:`| `Integer`                  | `2`                        | Max retry attempts on retryable errors       |
 | `retry_delay:`| `Numeric` (seconds)        | `0.5`                      | Base delay before the first retry            |
-| `timeout:`    | `Numeric` (seconds)        | `60`                       | Per-attempt timeout, body included           |
+| `timeout:`    | `Numeric` (seconds)        | `60`                       | Per-attempt timeout, body included; also bounds the PDF download |
 | `logger:`     | `Logger` (any duck type)   | `nil`                      | Hook errors and DEBUG events here            |
 | `on_retry:`   | `#call(PoliPage::RetryEvent)`| `nil`                    | Called when a retry is scheduled             |
 | `on_error:`   | `#call(PoliPage::Error)`   | `nil`                      | Called when a call terminates in error       |
@@ -293,6 +306,24 @@ end
 The full list of known API codes lives in `PoliPage::ErrorCodes` (see
 `lib/poli_page/errors.rb`).
 
+A 2xx answer whose body is not JSON, which comes from something between
+your app and the API (a proxy, a captive portal), raises
+`PoliPage::InvalidResponseError` (code `invalid_response`, message
+`Invalid response: HTTP <status> body is not JSON`) with the real 2xx as
+`status`. It is not retried.
+
+For framework integrations, `e.to_payload` returns the HTTP body to answer
+with: exactly the keys `code:`, `message:`, `status:` and `requestId:`, the
+same JSON in every Poli Page SDK. Its `status:` is the API status, 503 for
+`network_error`, 504 for `timeout` and 502 for `invalid_response`.
+
+```ruby
+rescue PoliPage::Error => e
+  payload = e.to_payload
+  render json: payload, status: payload[:status] || 500
+end
+```
+
 → Full error reference: <https://poli-page.github.io/sdk-ruby/reference/errors/>
 
 ## Cancellation

data/SECURITY.md

@@ -81,8 +81,10 @@ updates. Older minors do not receive backports — please upgrade.
   is pinned to a 40-character SHA, not a floating tag.
 - **Dependabot** — weekly updates for `bundler` and `github-actions`.
 - **MFA-required publishing** — the gemspec declares
-  `rubygems_mfa_required: "true"`; the per-gem RubyGems API key is
-  scoped to `poli-page` only.
+  `rubygems_mfa_required: "true"`. Releases are published by the tag-triggered
+  release workflow via RubyGems Trusted Publishing (OIDC), behind the
+  `rubygems-release` environment's required-reviewer approval; no RubyGems
+  API key is stored anywhere.
 - **Restricted workflow permissions** — every workflow declares the
   minimum `permissions:` block (most are `contents: read`).
 

data/lib/poli_page/client.rb

@@ -77,7 +77,7 @@ module PoliPage
 
     # Redacted `#inspect`. Ruby's default would dump `@api_key` into any
     # `puts client` or exception backtrace — that's how secrets end up in
-    # logs (sdk-ruby-plan.md §10.1 redaction rule).
+    # logs.
     def inspect
       "#<PoliPage::Client base_url=#{@base_url.inspect} timeout=#{@timeout} max_retries=#{@max_retries}>"
     end
@@ -220,17 +220,19 @@ module PoliPage
       { ok: false, error: error, retry_after: retry_after, retryable: retryable }
     end
 
-    # A 2xx whose body is not a JSON object (not JSON, empty, or another
-    # JSON value) raises `INTERNAL_ERROR`, not retried, through `on_error`
-    # like any error the SDK is about to raise (sdk-specification.md §4.1).
+    # A 2xx whose body is not JSON (an empty body included) raises
+    # `invalid_response` with the real status and the answer's request id; a
+    # JSON value that is not an object raises `INTERNAL_ERROR`. Neither is
+    # retried, and both go through `on_error` like any error the SDK is about
+    # to raise.
     def parse_json_response(response)
       parsed = JSON.parse(response.body.to_s)
       return Internal::Wire.from_wire(parsed, Internal::Wire::PAYLOAD_KEYS) if parsed.is_a?(Hash)
 
       raise_terminal(PoliPage::InternalError.new("response body was not a JSON object", status: response.status))
     rescue JSON::ParserError => e
-      raise_terminal(PoliPage::InternalError.new("response body was not valid JSON: #{e.message}",
-                                                 status: response.status, cause: e))
+      request_id = response.headers[Internal::Constants::HEADER_REQUEST_ID]
+      raise_terminal(PoliPage::InvalidResponseError.new(status: response.status, request_id: request_id, cause: e))
     end
 
     def fire_hook(hook, event)

data/lib/poli_page/documents.rb

@@ -8,7 +8,7 @@ require_relative "models/thumbnail"
 
 module PoliPage
   module Resources
-    # `client.documents` namespace (sdk-ruby-plan.md §13 Phase 4, port of
+    # `client.documents` namespace (port of
     # sdk-node/src/documents.ts).
     class Documents
       def initialize(client)

data/lib/poli_page/errors.rb

@@ -53,27 +53,34 @@ module PoliPage
 
     # A network error, a timeout, a 5xx or a 429, except the codes the SDK
     # never retries: `QUOTA_EXCEEDED`, `OVERAGE_CAP_EXCEEDED`,
-    # `STORAGE_ACCESS_DENIED`, and `DOWNLOAD_FAILED` whatever the storage
-    # status (the presigned-URL download is never retried).
+    # `STORAGE_ACCESS_DENIED`, `DOWNLOAD_FAILED` whatever the storage status
+    # (the presigned-URL download is never retried), `invalid_response` and
+    # `io_error`.
     def retryable?
-      return false if Internal::Constants::NON_RETRYABLE_CODES.include?(@code) || @code == "DOWNLOAD_FAILED"
+      return false if Internal::Constants::NON_RETRYABLE_CODES.include?(@code) ||
+                      Internal::Constants::NEVER_RETRIED_SDK_CODES.include?(@code)
       return true if network_error?
 
       !@status.nil? && (@status >= 500 || @status == 429)
     end
 
-    # Canonical wire payload for framework integrations:
-    # `{code:, message:, status:, request_id:}`. `status` surfaces 503 for
-    # connection failures, 504 for timeouts, the API HTTP status for
-    # status-bearing errors, and nil when unknown. The {#status} reader
-    # itself stays nil for transport-error instances — only the payload
-    # surfaces 503/504.
+    # The HTTP body a framework integration answers with: exactly the four
+    # keys `code`, `message`, `status` and `requestId`, spelled the same in
+    # every Poli Page SDK so that every integration answers the same JSON.
+    # `status` is the API status for status-bearing errors, 503 for
+    # `network_error`, 504 for `timeout`, 502 for `invalid_response`, and nil
+    # when unknown; `requestId` is nil when unknown. The {#status} reader
+    # itself is unchanged: nil for transport errors, the real 2xx for
+    # `invalid_response`.
+    #
+    # @return [Hash{Symbol=>(String, Integer, nil)}]
+    #   `{ code:, message:, status:, requestId: }`
     def to_payload
       {
         code: @code,
         message: message,
         status: payload_status,
-        request_id: @request_id
+        requestId: @request_id
       }
     end
 
@@ -144,11 +151,15 @@ module PoliPage
   # `DOWNLOAD_FAILED`: the presigned-URL download failed. With the storage's
   # `status` when it answered (`Failed to download PDF: HTTP <status>`),
   # without one when no complete answer came (`Failed to download PDF:
-  # network error`, the HTTP library's exception as {#cause}). Never retried.
+  # network error`, the HTTP library's exception as {#cause}) or when the
+  # client's `timeout` elapsed (`timeout: true`, `Failed to download PDF:
+  # timeout`). Never retried, and {#retryable?} is false whatever the status.
   class DownloadError < Error
-    def initialize(status: nil, cause: nil, message: nil)
+    def initialize(status: nil, cause: nil, message: nil, timeout: false)
       message ||= if status
                     format(Internal::Constants::MESSAGE_DOWNLOAD_FAILED, status: status)
+                  elsif timeout
+                    Internal::Constants::MESSAGE_DOWNLOAD_FAILED_TIMEOUT
                   else
                     Internal::Constants::MESSAGE_DOWNLOAD_FAILED_NETWORK
                   end
@@ -156,6 +167,37 @@ module PoliPage
     end
   end
 
+  # `invalid_response`: a 2xx answer whose body is not JSON, from a method
+  # that expects JSON (the API call of `render.document`, `render.pdf` and
+  # `render.pdf_stream`, `documents.get`, `documents.thumbnails`). Such a body
+  # comes from something between the SDK and the API, such as a proxy or a
+  # captive portal. `status` is the real 2xx and `request_id` the answer's
+  # `x-request-id`; the JSON parser's error is {#cause}. Never retried.
+  # {#to_payload} answers 502: an integration must not answer an error with a
+  # 2xx.
+  class InvalidResponseError < Error
+    def initialize(status:, request_id: nil, cause: nil)
+      super(format(Internal::Constants::MESSAGE_INVALID_RESPONSE, status: status),
+            code: "invalid_response", status: status, request_id: request_id, cause: cause)
+    end
+
+    def payload_status
+      502
+    end
+  end
+
+  # `io_error`: `Client#render_to_file` could not write the file (creating a
+  # parent directory, opening, writing or moving it into place). Message
+  # `Failed to write PDF: <reason>`, `<reason>` being the Ruby error's own
+  # message; that error is {#cause}. No status, never retried. The target
+  # file is left untouched.
+  class FileWriteError < Error
+    def initialize(cause:)
+      super(format(Internal::Constants::MESSAGE_IO_ERROR, reason: cause.message),
+            code: "io_error", status: nil, request_id: nil, cause: cause)
+    end
+  end
+
   class InternalError < Error
     def initialize(message, status: nil, cause: nil)
       super(message, code: "INTERNAL_ERROR", status: status, request_id: nil, cause: cause)

data/lib/poli_page/internal/constants.rb

@@ -24,6 +24,11 @@ module PoliPage
       # the bucket access is restored.
       NON_RETRYABLE_CODES = %w[QUOTA_EXCEEDED OVERAGE_CAP_EXCEEDED STORAGE_ACCESS_DENIED].freeze
 
+      # SDK codes never retried and never `retryable?`: the presigned-URL
+      # download, a 2xx whose body is not JSON (whatever answered it will
+      # answer the same again) and a file that cannot be written.
+      NEVER_RETRIED_SDK_CODES = %w[DOWNLOAD_FAILED invalid_response io_error].freeze
+
       # SDK error messages: exact texts of sdk-specification.md §8.3, the same
       # in every SDK (the API contract's `policy.sdkErrors` compares them).
       MESSAGE_INVALID_OPTIONS         = "apiKey is required"
@@ -31,6 +36,9 @@ module PoliPage
       MESSAGE_TIMEOUT                 = "Request timed out after %<timeout_ms>dms"
       MESSAGE_DOWNLOAD_FAILED         = "Failed to download PDF: HTTP %<status>d"
       MESSAGE_DOWNLOAD_FAILED_NETWORK = "Failed to download PDF: network error"
+      MESSAGE_DOWNLOAD_FAILED_TIMEOUT = "Failed to download PDF: timeout"
+      MESSAGE_INVALID_RESPONSE        = "Invalid response: HTTP %<status>d body is not JSON"
+      MESSAGE_IO_ERROR                = "Failed to write PDF: %<reason>s"
       MESSAGE_PROJECT_REQUIRED        = "project is required"
 
       # Header names (lowercase form — Net::HTTP normalises to lowercase on

data/lib/poli_page/internal/http.rb

@@ -10,7 +10,7 @@ module PoliPage
     # @api private
     #
     # Pure transport helpers — no I/O, no socket access. Mirrors
-    # `sdk-node/src/internal/http.ts` (sdk-ruby-plan.md §13 Phase 1).
+    # `sdk-node/src/internal/http.ts`.
     module HTTP
       module_function
 
@@ -115,7 +115,7 @@ module PoliPage
       end
 
       # Map an API response (status + parsed code/message) to the most
-      # specific `PoliPage::Error` subclass (sdk-ruby-plan.md §7).
+      # specific `PoliPage::Error` subclass.
       #
       # @param status     [Integer]
       # @param code       [String]

data/lib/poli_page/internal/presigned_fetch.rb

@@ -1,9 +1,12 @@
 # frozen_string_literal: true
 
 require "net/http"
+require "timeout"
 require "uri"
 
+require_relative "http"
 require_relative "transport"
+require_relative "watchdog"
 
 module PoliPage
   module Internal
@@ -11,61 +14,134 @@ module PoliPage
     #
     # Mixin used by `PoliPage::Client` for the unauthenticated presigned-URL
     # second hop (DocumentDescriptor#download_pdf, render.pdf, pdf_stream).
-    # The presigned URL is signed by S3 and MUST NOT be retried by the SDK
-    # (sdk-specification.md §7.2, §9.1): the `Net::HTTP` it uses has
-    # `max_retries` 0, so it never sends the GET twice either.
+    # The presigned URL is signed by the storage and is never retried by the
+    # SDK: the `Net::HTTP` it uses has `max_retries` 0, so it never sends the
+    # GET twice either.
     #
     # Every failure is `PoliPage::DownloadError` (`DOWNLOAD_FAILED`): with the
-    # storage status on a non-2xx answer, with the network message when no
-    # complete answer came (a connection error, a dropped body or a timeout).
+    # storage status on a non-2xx answer, with the timeout message when the
+    # client's `timeout` elapsed, and with the network message when no
+    # complete answer came otherwise (a connection error, or a body cut short
+    # of its `Content-Length`).
+    #
+    # The client's `timeout` (seconds) bounds the download:
+    #
+    # - {#fetch_bytes} (`download_pdf`, `render.pdf`): the whole download,
+    #   from opening the connection to the last byte of the body.
+    # - {#stream_bytes} (`render.pdf_stream`, `render_to_file`): an idle
+    #   timeout. Opening the connection, the request, the answer's head and
+    #   the first chunk of the body share one deadline; then each wait for
+    #   the next chunk is bounded on its own (`Net::HTTP`'s `read_timeout`),
+    #   so a large PDF read at the caller's pace is not cut off. Time spent
+    #   in the caller's block is never counted.
+    #
+    # A failure is labelled a timeout only when one of those bounds fired:
+    # `Net::HTTP`'s own `Net::OpenTimeout` / `Net::ReadTimeout` /
+    # `Net::WriteTimeout`, or the {Watchdog} closing the connection at the
+    # deadline. A `timeout` of zero or less has already passed, so the
+    # download fails at once with the timeout message, as an API call does.
     #
     # Honors the same proxy/CA configuration as {PoliPage::Internal::Transport}
     # — reads `@proxy`, `@ca_file`, `@ca_path`, `@timeout` from the including
-    # `Client` instance. `@timeout` bounds each socket operation (connect, and
-    # every read), not the whole download, so a long `pdf_stream` is not cut.
+    # `Client` instance.
     module PresignedFetch
       # Fetch the entire body of `url`. Returns the raw bytes; raises
-      # PoliPage::DownloadError on non-2xx or network failure.
+      # PoliPage::DownloadError on non-2xx, network failure or timeout.
       def fetch_bytes(url)
         uri = URI.parse(url)
         http = presigned_http(uri)
-        response = http.start do
-          http.request(Net::HTTP::Get.new(uri.request_uri)) do |res|
-            guard_presigned_status!(res)
-            res.read_body
+        download = new_download
+        presigned_request(http, download) do
+          watchdog = download[:watchdog] = Watchdog.new(presigned_time_left(download)) { http.finish }
+          begin
+            http.request(Net::HTTP::Get.new(uri.request_uri)) do |res|
+              guard_presigned_status!(res)
+              res.read_body
+            end.body
+          ensure
+            watchdog.disarm
           end
         end
-        response.body
-      rescue *Transport::NETWORK_ERRORS => e
-        raise PoliPage::DownloadError.new(cause: e)
       end
 
       # Stream the body of `url` to the block. Raises PoliPage::DownloadError
-      # on non-2xx or network failure and PoliPage::InternalError on
-      # Content-Length: 0 (port of Node `render.ts:128-130` `!response.body`
-      # guard). An error raised by the block itself propagates unchanged.
+      # on non-2xx, network failure or timeout (before the first chunk, or
+      # between two chunks), and PoliPage::InternalError on Content-Length: 0
+      # (port of Node `render.ts:128-130` `!response.body` guard). An error
+      # raised by the block itself propagates unchanged.
       def stream_bytes(url, &block)
         uri = URI.parse(url)
         http = presigned_http(uri)
-        in_block = false
-        http.start do
+        download = new_download
+        presigned_request(http, download) { stream_body(http, uri, download, block) }
+        nil
+      end
+
+      private
+
+      def new_download
+        { deadline: HTTP.monotonic_now + @timeout, watchdog: nil, in_block: false, first_chunk_in: false }
+      end
+
+      # The first-byte watchdog bounds the request, the answer's head and the
+      # wait for the first chunk of the body; it is disarmed when that chunk
+      # arrives, and `read_timeout` then bounds each wait for the next one.
+      # The `ensure` disarms it for an empty body or an error.
+      def stream_body(http, uri, download, block)
+        watchdog = download[:watchdog] = Watchdog.new(presigned_time_left(download)) { http.finish }
+        begin
           http.request(Net::HTTP::Get.new(uri.request_uri)) do |response|
             guard_stream!(response)
-            response.read_body do |chunk|
-              in_block = true
-              block.call(chunk)
-              in_block = false
-            end
+            response.read_body { |chunk| yield_chunk(download, block, chunk) }
           end
+        ensure
+          watchdog.disarm
         end
-        nil
-      rescue *Transport::NETWORK_ERRORS => e
-        raise if in_block
+      end
 
-        raise PoliPage::DownloadError.new(cause: e)
+      def yield_chunk(download, block, chunk)
+        unless download[:first_chunk_in]
+          download[:watchdog].disarm
+          download[:first_chunk_in] = true
+        end
+        download[:in_block] = true
+        block.call(chunk)
+        download[:in_block] = false
       end
 
-      private
+      # Opens the connection within the time left, runs the request, closes
+      # the connection, and turns a failure of the download into a
+      # `DownloadError`. A `PoliPage::Error` (a non-2xx status) and an error
+      # raised by the caller's block go through unchanged.
+      def presigned_request(http, download)
+        Timeout.timeout(presigned_time_left(download), Net::OpenTimeout) { http.start }
+        begin
+          yield
+        ensure
+          http.finish if http.started?
+        end
+      rescue StandardError => e
+        raise if e.is_a?(PoliPage::Error) || download[:in_block]
+
+        raise_download_failure(e, download)
+      end
+
+      # Once the watchdog has closed the connection, whatever `Net::HTTP`
+      # raises next is that timeout.
+      def raise_download_failure(error, download)
+        timed_out = download[:watchdog]&.fired? || Transport::SOCKET_TIMEOUTS.any? { |klass| error.is_a?(klass) }
+        raise PoliPage::DownloadError.new(timeout: true, cause: error) if timed_out
+        raise error unless Transport::NETWORK_ERRORS.any? { |klass| error.is_a?(klass) }
+
+        raise PoliPage::DownloadError.new(cause: error)
+      end
+
+      def presigned_time_left(download)
+        left = download[:deadline] - HTTP.monotonic_now
+        raise Net::OpenTimeout, "the download's timeout has passed" unless left.positive?
+
+        left
+      end
 
       def presigned_http(uri)
         Transport.build_http(uri, timeout: @timeout, proxy: @proxy, ca_file: @ca_file, ca_path: @ca_path)

data/lib/poli_page/internal/transport.rb

@@ -14,7 +14,7 @@ module PoliPage
     # @api private
     #
     # Thin wrapper around `Net::HTTP`. The ONLY module that opens sockets to
-    # the API (sdk-ruby-plan.md §3.2). Translates network-level exceptions into
+    # the API. Translates network-level exceptions into
     # the `PoliPage::Error` hierarchy at the seam (§8 error mapping).
     #
     # Each attempt opens its own connection and reads the whole answer, body

data/lib/poli_page/internal/uuid.rb

@@ -8,7 +8,7 @@ module PoliPage
     #
     # Thin wrapper over `SecureRandom.uuid`. Indirection exists so a future
     # swap (e.g. UUIDv7 once the stdlib lands `SecureRandom.uuid_v7`) is a
-    # one-file change (sdk-ruby-plan.md §13 Phase 1).
+    # one-file change.
     module UUID
       module_function
 

data/lib/poli_page/internal/wire.rb

@@ -5,7 +5,7 @@ module PoliPage
     # @api private
     #
     # snake_case ↔ camelCase translator for the SDK's own field names
-    # (sdk-ruby-plan.md §5.4, sdk-specification.md §2). Pure, no runtime
+    # (sdk-specification.md §2). Pure, no runtime
     # dependency on metaprogramming DSLs. Outgoing: hash keys are stringified
     # and camelized. Incoming: hash keys are snake_cased and symbolized.
     #

data/lib/poli_page/models/document_descriptor.rb

@@ -6,7 +6,7 @@ module PoliPage
   # SDK-attached `_client` back-reference used by `#download_pdf`.
   #
   # The `_client` field is hidden from `#to_h` and `#inspect` so it doesn't
-  # leak into logs or marshalled representations (sdk-ruby-plan.md §3.4).
+  # leak into logs or marshalled representations.
   DocumentDescriptor = Data.define(
     :document_id,
     :organization_id,

data/lib/poli_page/models/document_preview_result.rb

@@ -4,6 +4,6 @@ module PoliPage
   # Return value of `client.documents.preview`: the stored HTML of an
   # already rendered document, with `page_count` read from the
   # `X-Document-Page-Count` response header on a `text/html` body
-  # (sdk-ruby-plan.md §13 Phase 4; mirrors Node `documents.ts:75-77`).
+  # (mirrors Node `documents.ts:75-77`).
   DocumentPreviewResult = Data.define(:html, :page_count)
 end

data/lib/poli_page/render.rb

@@ -5,8 +5,7 @@ require_relative "models/document_descriptor"
 module PoliPage
   module Resources
     # `client.render` namespace. Each method captures a back-reference to the
-    # parent `PoliPage::Client` and delegates HTTP execution through it
-    # (sdk-ruby-plan.md §3.1).
+    # parent `PoliPage::Client` and delegates HTTP execution through it.
     class Render
       def initialize(client)
         @client = client

data/lib/poli_page/render_to_file.rb

@@ -2,19 +2,30 @@
 
 require "fileutils"
 require "pathname"
+require "tempfile"
 
 module PoliPage
   class Client
-    # Render a PDF and stream the bytes straight to `path`. Built on
+    # Render a PDF and stream the bytes to `path`. Built on
     # `render.pdf_stream`, so memory usage stays bounded regardless of
-    # document size. Creates parent directories if missing. Overwrites
-    # existing files. On render error the partial file is removed before
-    # the error is re-raised.
+    # document size. Creates parent directories if missing, and replaces an
+    # existing file.
+    #
+    # The PDF is written to a temporary file in the target's directory, which
+    # is renamed over `path` only once the whole PDF is in. When anything
+    # fails (the render, the download or the write), `path` is left as it
+    # was: an existing file keeps its content, a missing one is not created.
+    # The directory and the temporary file are prepared before the render,
+    # so a path that cannot be written costs no render. When `path` is a
+    # symbolic link, the PDF goes to the file it points to, and the link
+    # stays a link.
     #
     # @param path   [String, Pathname]
     # @param kwargs forwarded to `Resources::Render#pdf_stream`
     # @return       [nil]
-    # @raise        [PoliPage::InvalidOptionsError] on filesystem failure
+    # @raise        [PoliPage::FileWriteError] `io_error` when the file cannot be written (creating a
+    #   parent directory, opening, writing or moving it into place): message
+    #   `Failed to write PDF: <reason>`, the Ruby error as `cause`, no status, never retried
     # @raise        any error raised by `Resources::Render#pdf_stream`
     #
     # @example Write a PDF to disk
@@ -25,27 +36,93 @@ module PoliPage
     #     data:     { name: "World" }
     #   )
     def render_to_file(path, **kwargs)
-      pathname = Pathname(path)
-      FileUtils.mkdir_p(pathname.dirname) unless pathname.dirname.directory?
-
-      stream_to_path(pathname, kwargs)
+      target = file_write { resolve_links(Pathname(path)) }
+      temp = open_temp_file(target)
+      begin
+        render.pdf_stream(**kwargs) { |chunk| file_write { temp.write(chunk) } }
+        file_write { move_into_place(temp, target) }
+      ensure
+        discard_temp_file(temp)
+      end
       nil
-    rescue Errno::EACCES, Errno::ENOSPC, Errno::EISDIR, Errno::ENOENT, Errno::EROFS => e
-      raise PoliPage::InvalidOptionsError,
-            "failed to write to #{pathname}: #{e.class}: #{e.message}"
     end
 
+    # Errors of the file system: `Errno::*` and Ruby's own `IOError`.
+    FILE_WRITE_ERRORS = [SystemCallError, ::IOError].freeze
+    private_constant :FILE_WRITE_ERRORS
+
     private
 
-    def stream_to_path(pathname, kwargs)
-      File.open(pathname, "wb") do |io|
-        render.pdf_stream(**kwargs) { |chunk| io.write(chunk) }
+    def file_write
+      yield
+    rescue *FILE_WRITE_ERRORS => e
+      raise PoliPage::FileWriteError.new(cause: e)
+    end
+
+    # Most links the file system follows in one path (Linux's limit).
+    MAX_LINKS = 40
+    private_constant :MAX_LINKS
+
+    # The file `path` names once its symbolic links are followed, so the
+    # rename replaces that file, not the link. An existing file is its real
+    # path. A link whose target does not exist yet resolves, hop by hop, to
+    # that target, which the rename then creates: each relative link is read
+    # against the real directory of the link, as the file system does, so a
+    # `..` after a linked directory leaves the directory the link points to.
+    def resolve_links(path)
+      return Pathname(File.realpath(path)) if path.exist?
+
+      current = path.to_s
+      MAX_LINKS.times do
+        return Pathname(current) unless File.symlink?(current)
+
+        link = File.readlink(current)
+        current = File.absolute_path?(link) ? link : File.join(File.realpath(File.dirname(current)), link)
+      end
+      raise Errno::ELOOP, path.to_s
+    end
+
+    # The temporary file sits next to the target, so the final rename stays
+    # on one file system and replaces the target in one step.
+    #
+    # Two targets fail here, before any render, checked from the file's
+    # attributes without opening it: one that exists but is not a regular
+    # file (a directory, a FIFO, a device, a socket), which the rename would
+    # otherwise replace with a regular file, and one that cannot be written,
+    # as opening it for writing would fail (the rename could replace it even
+    # so). `target` is already resolved, so a link to a regular file passes.
+    def open_temp_file(target)
+      file_write do
+        raise ::IOError, "#{target}: not a regular file" if target.exist? && !target.file?
+        raise Errno::EACCES, target.to_s if target.exist? && !target.writable?
+
+        FileUtils.mkdir_p(target.dirname)
+        Tempfile.create([".#{target.basename}.", ".part"], target.dirname.to_s, binmode: true)
+      end
+    end
+
+    def move_into_place(temp, target)
+      temp.close
+      File.chmod(target_mode(target), temp.path)
+      File.rename(temp.path, target.to_s)
+    end
+
+    # The mode the file would get from a plain `File.open(path, "wb")`: an
+    # existing file keeps its own, a new one gets the umask's default (the
+    # temporary file is created owner-only).
+    def target_mode(target)
+      target.file? ? target.stat.mode & 0o7777 : 0o666 & ~File.umask
+    end
+
+    # Removes the temporary file, if still there. A failure to close it must
+    # not hide the outcome of the call, so it is ignored.
+    def discard_temp_file(temp)
+      begin
+        temp.close unless temp.closed?
+      rescue *FILE_WRITE_ERRORS
+        nil
       end
-    rescue StandardError
-      # Clean up the partial / empty file so the caller can see the failure
-      # cleanly. Mirrors Node `fs.createWriteStream` cleanup behaviour.
-      FileUtils.rm_f(pathname)
-      raise
+      FileUtils.rm_f(temp.path)
     end
   end
 end

data/lib/poli_page/retry_event.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module PoliPage
-  # Event payload for the `on_retry` constructor hook (sdk-ruby-plan.md §10.2).
+  # Event payload for the `on_retry` constructor hook.
   #
   # - `attempt`  [Integer]         1-based — the attempt about to be made.
   # - `delay_ms` [Integer]         sleep duration in milliseconds before this

data/lib/poli_page/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module PoliPage
-  VERSION = "0.11.0"
+  VERSION = "0.13.0"
 end

data/sig/poli_page/errors.rbs

@@ -14,7 +14,7 @@ module PoliPage
     def validation_error?: () -> bool
     def network_error?: () -> bool
     def retryable?: () -> bool
-    def to_payload: () -> { code: String, message: String, status: Integer?, request_id: String? }
+    def to_payload: () -> { code: String, message: String, status: Integer?, requestId: String? }
     def payload_status: () -> Integer?
   end
 
@@ -54,7 +54,15 @@ module PoliPage
   end
 
   class DownloadError < Error
-    def initialize: (?status: Integer?, ?cause: Exception?, ?message: String?) -> void
+    def initialize: (?status: Integer?, ?cause: Exception?, ?message: String?, ?timeout: bool) -> void
+  end
+
+  class InvalidResponseError < Error
+    def initialize: (status: Integer, ?request_id: String?, ?cause: Exception?) -> void
+  end
+
+  class FileWriteError < Error
+    def initialize: (cause: Exception) -> void
   end
 
   class InternalError < Error

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: poli-page
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.13.0
 platform: ruby
 authors:
 - Poli Page