Add optional synchronous mode to SSE::Client

[pekopekopekopayo]

Hello,

First of all, thank you very much for creating this gem — I really appreciate your work.

I would like to discuss the current behavior of SSE::Client.

Right now, SSE::Client always runs asynchronously, but I believe there are cases where an SSE client should behave synchronously. For example, if the architecture looks like:

AI <—> Backend Server <—> Frontend

there may be situations where the backend needs to wait for SSE responses and also return SSE responses to the frontend at the same time.
However, because the current implementation always runs asynchronously in a separate thread, the backend logic finishes immediately, making synchronous flow impossible.

Additionally, in read_stream, when data is nil, the code breaks out of the loop — which makes sense — but I think it should also explicitly call close to properly close the SSE connection.

If I’m misunderstanding something about SSE in general, I apologize.
I would really appreciate hearing your thoughts on these points.

Thank you very much.

module SSE
  class Client
    def initialize(..., async: true)
      if async
        thread = Thread.new { run_stream }
        thread.name = THREAD_NAME
      else
        run_stream
      end
    end
  end
end

[pekopekopekopayo]

I’m not very good at English, so I apologize if anything I said sounded rude or inappropriate. That was not my intention.

[jsonbailey]

@pekopekopekopayo you should be able to handle the proposed architecture with an async client using a queue and the pop method to block until it is done.

# Backend receives request from frontend
def handle_ai_proxy_request
  # Set up frontend SSE response
  response.headers['Content-Type'] = 'text/event-stream'
  response.headers['Cache-Control'] = 'no-cache'
  
  completion_queue = Queue.new
  
  # Connect to AI service (async)
  ai_client = SSE::Client.new(ai_service_url) do |client|
    client.on_event do |event|
      # Forward to frontend immediately
      response.write("data: #{event.data}\n\n")
      response.flush
      
      # Signal completion if needed
      completion_queue << :done if event.type == 'done'
    end
    
    client.on_error do |error|
      completion_queue << error
    end
  end
  
  # Option A: Return immediately, let events stream
  # (frontend receives events as they arrive)
  # ai_client.close when frontend disconnects
  
  # Option B: Wait for completion
  result = completion_queue.pop
  ai_client.close
  return result
end

[pekopekopekopayo]

@jsonbailey

Thank you for the response — your explanation makes sense to me.

I agree that in the pattern you described, the flow can behave synchronously once a specific event like "done" is detected. However, I was thinking that if the client provided something like an async: true/false option (or a similarly explicit argument), users wouldn’t need to understand the provider’s event structure or implement their own queue/condition logic.

In other words, if this behavior could be controlled through an optional argument, the library could handle the stream completion logic internally, and users wouldn’t need to inspect event types or implement synchronization themselves.

What do you think about this kind of approach?

[jsonbailey]

@pekopekopekopayo, Because stream completion logic varies by provider and application, and we want to keep this library focused on the core SSE protocol and let individual applications focus on processing and managing events.

I recommend creating a higher-level wrapper that handles your provider's completion semantics and uses a Queue or similar mechanism to coordinate with the async client—this keeps provider-specific logic out of the core library while giving you the control you need.

[pekopekopekopayo]

Thank you for your kind and helpful answer!