digiwin_dsp 0.4.2 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ea76bd5a8bb2c25914e0f9bd6c40ff1fdf5ac6c6c0e83b6652b9a4c20f26a33
-  data.tar.gz: bca70e0fd5ba6f33831f2aaf4cf61aa29987a241d958dadd20539a34490bbf53
+  metadata.gz: 813b05b6b115eed5a1fd308aa3c8a255da6df70afdf090101e7bfe0f74f605e7
+  data.tar.gz: 7ecfa001245bff0c95125f9667e303506ab9c1170bf8cce12f039c9773715bb4
 SHA512:
-  metadata.gz: dc0e854bc169fda091248b0048c9cf79ab0cad639b0cd431dfce867d3f9eaeaab737bad0f8103975bf9311efe99cd737b9bb05d65019cabfcb27ac8d77d1da7f
-  data.tar.gz: 619d56aa98ec48df0055bad21448618a244b8e29623429a07adaa8ca236229d7501ade6f978c69d7df3a495de1d5be6b5d6951e25f3ba050a18a9f6c4826176e
+  metadata.gz: 1086238addb8b6feb861d80f4c133c9e891e4b64ed45821ffc0dd68bde3a8e0ea7fadd009ee2b34dfa78e9a640fe2b22d8590a1b364d80b43081688771b53ebd
+  data.tar.gz: 12079e2663087764b54acae5b774e22398dc9ec48b3379684bfd6fdb0be51ef2604ac7d2db30e59bb7a9dae6bfdbac62b965c5c29b1ac1c1c7bf0c8247ab9fb2

data/CHANGELOG.md

@@ -6,6 +6,19 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-01
+
+### BREAKING
+
+- **Ruby 3.2 support dropped; supported range is now 3.3 – 4.0.** `required_ruby_version` is `>= 3.3.0` and CI runs 3.3 / 3.4 / 4.0. The dev-only `parallel < 2.0` pin (kept for the 3.2 CI row) is removed.
+
+### Fixed
+
+- **POSTs are no longer resent after a read timeout.** faraday-retry's defaults retried `Faraday::TimeoutError` for every method, so a slow DSP that had already created the order would see a resend and the caller would get a spurious `DuplicateRequestError` (or a real duplicate on invoice/return, which have no documented dedupe). Only failures that happen before the request is sent (connection refused, host/network unreachable, DNS failure, connect timeout) are retried now — which also makes the README's "connection failures" claim true; previously `Faraday::ConnectionFailed` was never retried.
+- **Non-object 2xx bodies raise `ServerError`** instead of being returned and blowing up as `NoMethodError` in `Resources::Base#create` / `WebhookSubscription#create` (outside the `DigiwinDsp::Error` tree, so `rescue`/`retry_on` missed it). A `{"std_data":"..."}` body no longer raises `TypeError` either.
+- **Malformed inbound webhooks raise `Webhooks::ParseError`** instead of `TypeError` when an envelope level isn't an object, and `InventoryUpdate` / `LogisticsUpdate` now reject a non-object `request` payload.
+- **`Configuration#environment=` accepts strings** (e.g. `c.environment = Rails.env`), matching the `DIGIWIN_DSP_ENV` path.
+
 ## [0.4.2] - 2026-06-18
 
 ### Added
@@ -264,7 +277,8 @@ Initial release. Covers the four Self-hosted Website Module (自有官網模組)
 - The gem is **synchronous on purpose**. Callers wrap requests in their own background job runner (e.g. ActiveJob) when needed.
 - Idempotency: clients can send `X-Idempotency-Key` via the `idempotency_key:` kwarg. DSP also dedupes server-side by `form_no + platform_id`.
 
-[Unreleased]: https://github.com/7a6163/digiwin_dsp/compare/v0.4.2...HEAD
+[Unreleased]: https://github.com/7a6163/digiwin_dsp/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/7a6163/digiwin_dsp/compare/v0.4.2...v0.5.0
 [0.4.2]: https://github.com/7a6163/digiwin_dsp/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/7a6163/digiwin_dsp/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/7a6163/digiwin_dsp/compare/v0.3.1...v0.4.0

data/README.md

@@ -1,10 +1,13 @@
 # digiwin_dsp
 
+[![Gem Version](https://badge.fury.io/rb/digiwin_dsp.svg)](https://badge.fury.io/rb/digiwin_dsp)
 [![CI](https://github.com/7a6163/digiwin_dsp/actions/workflows/ci.yml/badge.svg)](https://github.com/7a6163/digiwin_dsp/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/7a6163/digiwin_dsp/branch/main/graph/badge.svg)](https://codecov.io/gh/7a6163/digiwin_dsp)
-[![Ruby](https://img.shields.io/badge/ruby-%E2%89%A53.2-CC342D)](https://www.ruby-lang.org/)
+[![Ruby](https://img.shields.io/badge/ruby-3.3%E2%80%934.0-CC342D)](https://www.ruby-lang.org/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE.txt)
 
+Homepage: <https://rubygems.org/gems/digiwin_dsp>
+
 Ruby client for the Digiwin DSP Self-hosted Website Module (自有官網模組) API. Lets your storefront push orders, cancellations, invoice updates, and returns into the Digiwin ERP through the DSP gateway.
 
 | Operation | Resource | Endpoint |
@@ -29,7 +32,7 @@ gem "digiwin_dsp"
 bundle install
 ```
 
-Ruby ≥ 3.2 required.
+Ruby 3.3 – 4.0 supported (≥ 3.3 required).
 
 ## Configuration
 
@@ -227,7 +230,8 @@ Every `Client#post` already retries transparently inside Faraday:
 | Setting | Value |
 |---|---|
 | Attempts | up to 4 (1 original + max 3 retries) |
-| Triggers | HTTP 429, 500, 502, 503, 504, connection failures |
+| Triggers | HTTP 429, 500, 502, 503, 504; connection failures that happen *before* the request reaches DSP (refused, host/network unreachable, DNS failure, connect timeout) |
+| Never retried | Read timeouts and mid-request connection resets — DSP may already have processed the POST, so resending could duplicate it. These raise `NetworkError`; check DSP state before retrying |
 | Backoff | exponential — ~0.5s, ~1s, ~2s between attempts, ±50% jitter |
 
 So one `Resources::Order.create` call can take up to ~`4 × timeout + 3.5s` in the worst case (default `timeout` 10s → ~44s). **Size your job timeouts and queue latency budgets accordingly** — if you also add `retry_on` in ActiveJob/Sidekiq (recommended for `RateLimitError`, which DSP signals via the envelope and the gem does *not* retry internally), the two layers multiply.

data/lib/digiwin_dsp/client.rb

@@ -13,6 +13,29 @@ module DigiwinDsp
     RETRY_INTERVAL = 0.5
     RETRY_BACKOFF_FACTOR = 2
     RETRY_INTERVAL_RANDOMNESS = 0.5
+    # Transport failures that happen before the request reaches DSP, so a
+    # resend can't duplicate a POST. Read timeouts, ECONNRESET, EPIPE etc.
+    # are deliberately absent: DSP may already have processed the request.
+    PRE_SEND_ERRORS = [
+      Errno::ECONNREFUSED, Errno::EHOSTUNREACH, Errno::ENETUNREACH, SocketError, Net::OpenTimeout
+    ].freeze
+    RETRY_IF = lambda do |_env, error|
+      !error.is_a?(Faraday::ConnectionFailed) ||
+        PRE_SEND_ERRORS.any? { |klass| error.wrapped_exception.is_a?(klass) }
+    end
+    RETRY_OPTIONS = {
+      max: RETRY_MAX,
+      interval: RETRY_INTERVAL,
+      backoff_factor: RETRY_BACKOFF_FACTOR,
+      interval_randomness: RETRY_INTERVAL_RANDOMNESS,
+      retry_statuses: RETRY_STATUSES,
+      # Faraday::TimeoutError is left out: a read timeout on a POST must not
+      # be resent (see PRE_SEND_ERRORS).
+      exceptions: [Faraday::ConnectionFailed, Faraday::RetriableResponse],
+      # Empty methods routes every retry decision through RETRY_IF.
+      methods: [],
+      retry_if: RETRY_IF
+    }.freeze
     USER_AGENT = "digiwin_dsp/#{VERSION} (Faraday/#{Faraday::VERSION})".freeze
 
     STATUS_ERROR_MAP = {
@@ -67,13 +90,7 @@ module DigiwinDsp
     def connection
       @connection ||= Faraday.new(url: connection_base_url, headers: default_headers) do |f|
         f.request :json
-        f.request :retry,
-                  max: RETRY_MAX,
-                  interval: RETRY_INTERVAL,
-                  backoff_factor: RETRY_BACKOFF_FACTOR,
-                  interval_randomness: RETRY_INTERVAL_RANDOMNESS,
-                  retry_statuses: RETRY_STATUSES,
-                  methods: %i[get post put patch delete]
+        f.request :retry, RETRY_OPTIONS
         # max_nesting caps deserialization depth so a hostile / malformed DSP
         # response can't allocate unbounded memory (DoS guard on the parser).
         f.response :json, content_type: /\bjson\z/, parser_options: { max_nesting: 50 }
@@ -114,8 +131,12 @@ module DigiwinDsp
       klass.new(message, **error_attrs(status, body))
     end
 
+    # Every DSP endpoint answers with a JSON object; anything else on a 2xx
+    # (IIS HTML error page, empty body) would otherwise surface downstream
+    # as NoMethodError, outside the DigiwinDsp::Error tree. The body itself
+    # stays out of the message (PII).
     def inspect_envelope(body)
-      return body unless body.is_a?(Hash)
+      raise ServerError.new("DSP returned a non-JSON-object 2xx body (#{body.class})", http_status: 200) unless body.is_a?(Hash)
 
       failure = detect_envelope_failure(body)
       return body unless failure
@@ -128,7 +149,7 @@ module DigiwinDsp
     # - DSPOOFFICIAL100: { srvver, std_data: { execution: { code, description }, response } }
     # - DSPOOFFICIAL001-005: { Status, Message, response_detail }
     def detect_envelope_failure(body)
-      if (exec = body.dig("std_data", "execution"))
+      if (exec = execution_block(body))
         return nil if exec["code"].to_s == "0"
 
         { message: exec["description"].to_s, code: exec["code"] }
@@ -142,6 +163,13 @@ module DigiwinDsp
       end
     end
 
+    # Hash-checked dig: a 2xx like {"std_data":"x"} must not raise TypeError.
+    def execution_block(body)
+      std_data = body["std_data"]
+      exec = std_data["execution"] if std_data.is_a?(Hash)
+      exec if exec.is_a?(Hash)
+    end
+
     # Neither known envelope. If DSP ships a third shape, failures would
     # otherwise pass through as "success" silently — leave a trace.
     def warn_unknown_envelope(body)

data/lib/digiwin_dsp/configuration.rb

@@ -21,9 +21,15 @@ module DigiwinDsp
       production: "https://digiwindsp.digiwin.com/DSP/api/webhook"
     }.freeze
 
-    attr_accessor :api_key, :platform_id, :environment, :logger,
+    attr_accessor :api_key, :platform_id, :logger,
                   :timeout, :open_timeout, :allowed_hosts
     attr_writer :base_url, :webhook_base_url
+    attr_reader :environment
+
+    # Accept strings too (e.g. `c.environment = Rails.env`), like the ENV path.
+    def environment=(value)
+      @environment = value&.to_sym
+    end
 
     def initialize
       @api_key           = ENV["DIGIWIN_DSP_API_KEY"]

data/lib/digiwin_dsp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DigiwinDsp
-  VERSION = "0.4.2"
+  VERSION = "0.5.0"
 end

data/lib/digiwin_dsp/webhooks/event.rb

@@ -26,8 +26,13 @@ module DigiwinDsp
       def self.extract_request(hash)
         raise ParseError, "envelope must be a JSON object" unless hash.is_a?(Hash)
 
-        hash.dig("digi_body", "std_data", "parameter", "request") ||
-          raise(ParseError, "envelope missing digi_body.std_data.parameter.request")
+        # Walk by hand: Hash#dig raises TypeError when an intermediate level
+        # is a String/Array, which would escape the DigiwinDsp::Error tree
+        # (webhooks are unsigned, so anyone can send such a body).
+        request = %w[digi_body std_data parameter request].reduce(hash) do |node, key|
+          node.is_a?(Hash) ? node[key] : nil
+        end
+        request || raise(ParseError, "envelope missing digi_body.std_data.parameter.request")
       end
 
       private_class_method :parse_json, :extract_request

data/lib/digiwin_dsp/webhooks/inventory_update.rb

@@ -6,6 +6,13 @@ module DigiwinDsp
     # See docs/dsp-specs/DSPOOFFICIAL100.yaml under
     # "庫存數量更新 product/inventory_update".
     class InventoryUpdate < Event
+      def self.parse(raw_body)
+        event = super
+        raise ParseError, "product/inventory_update payload must be a JSON object" unless event.request.is_a?(Hash)
+
+        event
+      end
+
       def prod         = request["prod"]
       def platform_id  = request["platform_id"]
       def sale_page_id = request["sale_page_id"]

data/lib/digiwin_dsp/webhooks/logistics_update.rb

@@ -6,6 +6,13 @@ module DigiwinDsp
     # delivered, etc.). See docs/dsp-specs/DSPOOFFICIAL100.yaml under
     # "倉儲貨態更新 wms/logistics/package/update".
     class LogisticsUpdate < Event
+      def self.parse(raw_body)
+        event = super
+        raise ParseError, "wms/logistics/package/update payload must be a JSON object" unless event.request.is_a?(Hash)
+
+        event
+      end
+
       def form_no          = request["form_no"]
       def func_name        = request["func_name"]
       def status_date      = request["status_date"]

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: digiwin_dsp
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.0
 platform: ruby
 authors:
 - Zac
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-18 00:00:00.000000000 Z
+date: 2026-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -101,7 +101,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="