Skip negative SSE retry spans and render with UInt64

Follow-up to #771: negative retry values are ignored by clients per the
SSE spec, so the field is now omitted entirely when the span is negative.
With negatives guarded, the retry value renders via .to_u64 so the type
reflects that only non-negative milliseconds are emitted.

Author: hahwul

.github/skills/kemal-sse/SKILL.md

@@ -12,6 +12,7 @@ This skill provides expert guidance on implementing real-time unidirectional eve
 
 - `sse` route helper and `Kemal::EventStream` (named events, `id:`, `retry:`): since Kemal 1.12.0.
 - SSE injection protection (CR/LF rejected in `event`/`id`, CRLF normalization in `data` and comments) and the `retry` field Int32 overflow fix: since Kemal 1.13.0.
+- Negative `retry` spans are omitted from the output (clients discard non-digit values): unreleased, after Kemal 1.13.0.
 
 ## Core Mandates
 

CHANGELOG.md

@@ -1,5 +1,7 @@
 # Unreleased
 
+- Omit the SSE `retry` field for negative `Time::Span` values instead of emitting e.g. `retry: -3000`, which clients discard per the SSE spec. The value now renders via `.to_u64`; output for non-negative spans is unchanged.
+
 - Skip filter tree lookups when no path-scoped filters are registered. Apps using only global filters (`before_all` and friends) no longer pay 4-6 radix lookups and key allocations per request [#781](https://github.com/kemalcr/kemal/pull/781).
 
 - Cache the `Date` response header string per second instead of formatting it on every request. The value is unchanged: the string is reused only within the same UTC second [#781](https://github.com/kemalcr/kemal/pull/781).

spec/event_stream_spec.cr

@@ -36,6 +36,26 @@ describe Kemal::EventStream do
     client_response.body.should eq("retry: 5184000000\ndata: update\n\n")
   end
 
+  it "emits a zero retry span" do
+    sse "/events" do |stream, _|
+      stream.send("update", retry: 0.seconds)
+    end
+
+    request = HTTP::Request.new("GET", "/events")
+    client_response = call_request_on_app(request)
+    client_response.body.should eq("retry: 0\ndata: update\n\n")
+  end
+
+  it "omits negative retry spans" do
+    sse "/events" do |stream, _|
+      stream.send("update", retry: -3.seconds)
+    end
+
+    request = HTTP::Request.new("GET", "/events")
+    client_response = call_request_on_app(request)
+    client_response.body.should eq("data: update\n\n")
+  end
+
   it "splits multi-line data into separate data fields" do
     sse "/events" do |stream, _|
       stream.send("line one\nline two")

src/kemal/event_stream.cr

@@ -19,7 +19,8 @@ module Kemal
 
     # Sends an SSE event. Multi-line *data* is split into separate `data:` fields.
     # *event* and *id* must not contain CR/LF; newlines there raise `ArgumentError`
-    # so they cannot inject SSE fields.
+    # so they cannot inject SSE fields. A negative *retry* span is omitted from the
+    # output, since clients discard non-digit `retry` values anyway.
     def send(data : String, *, event : String? = nil, id : String | Int? = nil, retry : Time::Span? = nil) : self
       if event
         validate_single_line!("event", event)
@@ -30,7 +31,11 @@ module Kemal
         validate_single_line!("id", id_value)
         @response.puts "id: #{id_value}"
       end
-      @response.puts "retry: #{retry.total_milliseconds.to_i64}" if retry
+      # Clients discard non-digit retry values (WHATWG HTML), so negative spans are
+      # skipped. The guard also protects to_u64 below, which raises on negatives.
+      if retry && !retry.negative?
+        @response.puts "retry: #{retry.total_milliseconds.to_u64}"
+      end
       each_sse_line(data) do |line|
         @response.puts "data: #{line}"
       end