letterapp 0.2.0 → 0.2.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0f2fde121f30391e8ef7d0272b8b8ca855d13f8597f90618ca493969eef045c2
-  data.tar.gz: 2647178c2d51cb3edbf7aace4aa8c71343321434107d5d55c06e8d75407a05f0
+  metadata.gz: 6a28e33d3a0a3f740b0d45a1a53c22983dbd781fba93c87dc8a167ae51075bc6
+  data.tar.gz: 643ca3a372bf627e1cea174989880196ce66c722da3ebfdd605e35d4bd8373b8
 SHA512:
-  metadata.gz: d5b5f7fa5a456b68b32659ffa690f3550e6f6ae618be9f54cab3462d7e2676d31eaf2ebe75a1ab09c04fc0525ae813fc2c7cece6a25f3ea472efbb317df0dafe
-  data.tar.gz: cfc610d764cf25e18d0894f14bc440613a72945ebc5441d3bb1d86d706832f4f6b28401581fdc6b3fddcbaa381514e8ad9d599c594ef3bb14877c33fc213d691
+  metadata.gz: 334a7ce7651803672d8d46bc37c97924bf18a556513a66d879ab0dfb6cf8f5559db138f3501bccc1e23ca4836071c4512a8c3886ff69eb8759b9273a13865080
+  data.tar.gz: 25819b5ad570ceec7b853f19bc2629a6b5a2c5b27e10849a5994e0d6e616c4335b616fd5c0be7e88f33419d60a2f7b73ee61e0d809db52aeb350ab0c32edce82

data/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+## 0.2.2 - 2026-10-25
+
+### Fixed
+
+- Sending mail through the `:letter` ActionMailer delivery method no longer
+  leaks a thread per message. `Client.new` started the batching thread, and
+  registered an `at_exit` hook holding the client, even for a client that
+  only calls `send_email`; Mail builds a new delivery method, and so a new
+  client, for every message. A long-running process kept one idle thread and
+  one client per email sent. The thread now starts with the first `identify`,
+  `group` or `track` call.
+- A client created before a fork (a Rails initializer under Puma cluster mode
+  or Solid Queue) now sends from the forked process as usual. The child
+  inherited a dead copy of the parent's thread, so its `identify`, `group` and
+  `track` calls waited in the queue until the process exited. The client now
+  starts a new thread when the old one is dead.
+
+## 0.2.1 - 2026-10-25
+
+### Fixed
+
+- `Letterapp::Client` no longer breaks Active Support's `present?`, `blank?`
+  and `presence`. 0.2.0 had a private `blank?(value)` helper that shadowed
+  `Object#blank?`, so in a Rails app `client.present?` and `client.presence`
+  raised `ArgumentError: wrong number of arguments (given 0, expected 1)`, and
+  `client.blank?` raised `NoMethodError`. The helper is now named `missing?`.
+
+## 0.2.0 - 2026-08-20
+
+### Added
+
+- `send_email` for transactional email (`POST /v1/send`), with
+  `idempotency_key:` for replay-safe retries.
+- `Letterapp::DeliveryMethod`, registered as `:letter` with ActionMailer in a
+  Rails app.
+- `Letterapp::Error#code` and `#reason`, from the API's error body.
+
+## 0.1.0 - 2026-05-29
+
+- First release: `identify`, `group` and `track`, auto-batched in the
+  background, with retries and idempotent message IDs.

data/lib/letterapp/client.rb

@@ -34,8 +34,9 @@ module Letterapp
   # A Letter client.
   #
   # Long-running server (default): identify / group / track enqueue calls that a
-  # background thread auto-batches and flushes every 100ms or 50 events. Call
-  # +close+ before the process exits.
+  # background thread auto-batches and flushes every 100ms or 50 events. The
+  # thread starts with the first queued call. Call +close+ before the process
+  # exits.
   #
   # Serverless: pass flush_at: 1 and call +flush+ at the end of each invocation.
   #
@@ -69,9 +70,7 @@ module Letterapp
       @cond = ConditionVariable.new
       @send_mutex = Mutex.new
       @closed = false
-
-      @thread = Thread.new { loop_run }
-      at_exit { close }
+      @thread = nil # see start_worker
     end
 
     # Queue an identify call (creates or updates a contact).
@@ -109,9 +108,9 @@ module Letterapp
     def send_email(to:, subject:, html: nil, text: nil, from: nil, from_name: nil,
                    reply_to: nil, headers: nil, tag: nil, metadata: nil,
                    idempotency_key: nil)
-      raise Error, "send_email: to is required" if blank?(to)
-      raise Error, "send_email: subject is required" if blank?(subject)
-      raise Error, "send_email: provide html, text, or both" if blank?(html) && blank?(text)
+      raise Error, "send_email: to is required" if missing?(to)
+      raise Error, "send_email: subject is required" if missing?(subject)
+      raise Error, "send_email: provide html, text, or both" if missing?(html) && missing?(text)
 
       body = { "to" => to, "subject" => subject }
       {
@@ -154,10 +153,23 @@ module Letterapp
           return
         end
         @queue << item
+        start_worker
         @cond.signal
       end
     end
 
+    # Starts the batching thread (and the at_exit hook that drains it) on the
+    # first queued call rather than in +initialize+. Mail builds a new delivery
+    # method, and so a new client, for every message; each one used to leave
+    # an idle thread behind. Also restarts a dead thread, which is what a
+    # forked child inherits from its parent. Called with @mutex held.
+    def start_worker
+      return if @thread&.alive?
+
+      at_exit { close } if @thread.nil?
+      @thread = Thread.new { loop_run }
+    end
+
     def take_batch
       @mutex.synchronize do
         return nil if @queue.empty?
@@ -248,7 +260,7 @@ module Letterapp
     end
 
     def serialize_identify(user_id, email, traits, timezone, timestamp, message_id)
-      raise Error, "identify: user_id is required" if blank?(user_id)
+      raise Error, "identify: user_id is required" if missing?(user_id)
 
       item = {
         "type" => "identify",
@@ -264,8 +276,8 @@ module Letterapp
     end
 
     def serialize_group(user_id, account_id, name, traits, timestamp, message_id)
-      raise Error, "group: user_id is required" if blank?(user_id)
-      raise Error, "group: account_id is required" if blank?(account_id)
+      raise Error, "group: user_id is required" if missing?(user_id)
+      raise Error, "group: account_id is required" if missing?(account_id)
 
       item = {
         "type" => "group",
@@ -281,8 +293,8 @@ module Letterapp
     end
 
     def serialize_track(user_id, event, properties, timestamp, message_id)
-      raise Error, "track: user_id is required" if blank?(user_id)
-      raise Error, "track: event is required" if blank?(event)
+      raise Error, "track: user_id is required" if missing?(user_id)
+      raise Error, "track: event is required" if missing?(event)
 
       item = {
         "type" => "track",
@@ -303,7 +315,10 @@ module Letterapp
       value.to_s
     end
 
-    def blank?(value)
+    # Not named +blank?+: Active Support defines Object#blank?, and its
+    # +present?+ and +presence+ call it, so a private blank?(value) here would
+    # shadow it and make +client.present?+ raise ArgumentError in a Rails app.
+    def missing?(value)
       value.nil? || value.to_s.empty?
     end
 

data/lib/letterapp/delivery_method.rb

@@ -82,14 +82,13 @@ module Letterapp
 
     private
 
+    # Mail builds a new delivery method for every message, so this client
+    # lives for one message. That's cheap: it only calls send_email, which
+    # bypasses the queue, so the client never starts its batching thread.
     def client
       @client ||= Client.new(
         api_key: settings.fetch(:api_key) { ENV.fetch("LETTER_API_KEY") },
-        base_url: settings[:base_url] || ENV["LETTER_BASE_URL"] || DEFAULT_BASE_URL,
-        # This client only ever calls send_email, which bypasses the queue, so
-        # the batching thread would sit idle forever. Setting flush_at to 1
-        # keeps it from being started for nothing.
-        flush_at: 1
+        base_url: settings[:base_url] || ENV["LETTER_BASE_URL"] || DEFAULT_BASE_URL
       )
     end
 

data/lib/letterapp/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Letterapp
-  VERSION = "0.2.0"
+  VERSION = "0.2.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: letterapp
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.2
 platform: ruby
 authors:
 - letter.app
@@ -16,6 +16,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/letterapp.rb
@@ -29,6 +30,7 @@ licenses:
 metadata:
   homepage_uri: https://letter.app/docs/ruby-sdk
   source_code_uri: https://github.com/vincenzor/letter-ruby
+  changelog_uri: https://github.com/vincenzor/letter-ruby/blob/main/CHANGELOG.md
   bug_tracker_uri: https://github.com/vincenzor/letter-ruby/issues
   rubygems_mfa_required: 'true'
 rdoc_options: []