Define how SSE works with the type safe clients about microprofile-rest-client

[andymc12]

I've got a working prototype of this issue going now - including spec text and TCK changes. One slight change to what I proposed previously - the return type should be Publisher<?> instead of CompletionSubscriber<?> (or even Subscriber<?>). This is more consistent with the notion that the client interface is a view of the server (which is publishing the SSE events) and allows a client app to subscribe to the publisher in order to consume the events.

The MP Reactive Streams Operators project depends on the org.reactivestreams APIs - and these APIs are basically duplicated/re-pacakaged in Java 9 as the Flow APIs. So I'm leaning toward making the MP Rest Client 2.0 work with both - since many people will want to run on Java 8 (using org.reactivestreams and the current versions of MP RSO) but other will want to run on Java 9+ and use the Flow API.

[andymc12]

Unless we decide to put MP Rest Client 1.0 in the MP 2.0 release, I think we should defer this issue. JAX-RS 2.1 (EE8) has SSE APIs that we should leverage to resolve this issue.

[johnament]

@andymc12 we had already decided in an early call to defer this until a release aligned w/ Java EE 8

[andymc12]

Something like this would be pretty cool:
https://dzone.com/articles/micronaut-mastery-consuming-server-sent-events-sse

[aguibert]

+1 for this feature request, currently I have to do something like this:

Client client = ClientBuilder.newClient();
WebTarget target = client.target(targetUrl);
try (SseEventSource source = SseEventSource.target(target).build()) {
    source.register(this::processInboundEvent,
                    (errEvent) -> errEvent.printStackTrace(),
                    () -> System.out.println("on close SSE"));
    source.open();
}

// ...

public void processInboundEvent(InboundSseEvent event) {
  // ...
}

This will be a bit different from other rest client usages because the "normal" (i.e. copy/pasting a JAX-RS endpoint method signature and removing the method body) way of defining an SSE client method would look like this:

    @GET
    @Produces(MediaType.SERVER_SENT_EVENTS)
    public void doThing(@Context SseEventSink sink, @Context Sse sse);

But this doesn't work because the user can not pass in an SseEventSink or Sse instance, and they need to be able to register their callbacks with an SseEventSource anyway.

So, perhaps we could define an SSE client method like this:

    @GET
    @Produces(MediaType.SERVER_SENT_EVENTS)
    public SseEventSource doThing(Consumer<InboundSseEvent> onEvent,
                                       Consumer<Throwable> on Error, // optional param
                                       Runnable onComplete); // optional param

Here, the REST Client impl would effectively do the following for the user:

public void doThing_RC_impl(Consumer<InboundSseEvent> onEvent,
                                       Consumer<Throwable> on Error, // optional param
                                       Runnable onComplete) // optional param
{
        Client client = ClientBuilder.newClient();
        String targetUrl = // discovered usual way with `@Path` and whatnot
        WebTarget target = client.target(targetUrl);
        SseEventSource source = SseEventSource.target(target).build());
        source.register(onEvent, onError, onComplete);
        source.open();
        return source; // return the SseEventSource so the caller can close it when they are done
}

[andymc12]

I'd prefer to use the new(-ish) MP Reactive Streams Operators so that SSE events can be "subscribed" to. Maybe something like this:

interface MyClient {

    @GET
    @Path("ssePath")
    @Consumes(MediaType.SERVER_SENT_EVENTS)
    CompletionSubscriber<MyEventType> getEvents();
}

Users could then receive events (that the implementation would have already converted to the type they want - without the app code needing to call inboundSseEvent.readData(MyEventType.class) via the subscriber.

We could also make a special case for CompletionSubscriber<InboundSseEvent> for cases where the client wants to do the type conversion - the use case for this might be where a service sends events of different types.