Skip to content

feat: API for Server Sent Events (SSE) streaming from HTTP endpoint - #213

Merged
johanandren merged 8 commits into
mainfrom
wip-sse-responses
Feb 14, 2025
Merged

johanandren merged 8 commits into
mainfrom
wip-sse-responses

Conversation

@johanandren

@johanandren johanandren commented Feb 13, 2025 •

Copy link
Copy Markdown
Contributor

References https://github.com/lightbend/kalix-runtime/issues/3094

Not sure if we should have some reference docs, or if it is enough of discoverability with the static factory since it is a power user kid of feature.

@github-actions github-actions Bot added documentation documentation related java-sdk labels Feb 13, 2025

@efgpinto efgpinto left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think eventually we will end up adding one of these in docs.. but maybe it can wait.

LGTM.

@patriknw patriknw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking good, I think we should mention in reference docs with a snippet that shows how it could poll an entity with component client requests.

@johanandren

Copy link
Copy Markdown
Contributor Author

Added a sample polling an entity, deduplicating so that only changes are emitted. I think this is nice to have in a sample but too complex to put in docs though.

Not sure what a realistic example that is much simpler would be except the streaming view updates.

return Collections.emptyList();
}
};
});

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

more elegant with scan?

  private record CustomerStreamState(Optional<Customer> customer, boolean isSame) {}

  @Get("/stream-customer-changes/{customerId}")
  public HttpResponse streamCustomerChanges(String customerId) {
    Source<Optional<Customer>, Cancellable> stateEvery5Seconds =
        // stream of ticks, one immediately, then one every five seconds
        Source.tick(Duration.ZERO, Duration.ofSeconds(5), "tick")
            // for each tick, request the entity state
            .mapAsync(1, __ ->
                componentClient.forKeyValueEntity(customerId)
                    .method(CustomerEntity::getCustomer)
                    .invokeAsync().handle((Customer customer, Throwable error) -> {
                      if (error == null) {
                        return Optional.of(customer);
                      } else if (error instanceof IllegalArgumentException) {
                        // calling getCustomer throws IllegalArgument if the customer does not exist
                        // we want the stream to continue polling in that case, so turn it into an empty optional
                        return Optional.<Customer>empty();
                      } else {
                        throw new RuntimeException("Unexpected error polling customer state", error);
                      }
                    })
            );

    // deduplicate, so that we don't emit if the state did not change from last time
    Source<Customer, Cancellable> streamOfChanges =
        stateEvery5Seconds.scan(new CustomerStreamState(Optional.empty(), true),
                (state, newCustomer) ->
                    new CustomerStreamState(newCustomer, state.customer.equals(newCustomer))
            )
            .filterNot(state -> state.isSame || state.customer.isEmpty())
            .map(state -> state.customer.get());

    // now turn each changed internal state representation into public API representation,
    // just like get endpoint above
    Source<CustomerRequest, Cancellable> streamOfChangesAsApiType = streamOfChanges.map(c ->
        new CustomerRequest(customerId, c.name(), c.email(), c.address().city(), c.address().street())
    );

    // turn into server sent event response
    return HttpResponses.serverSentEvents(streamOfChangesAsApiType);
  }

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, neat, I didn't think of that, I'll change. Might still not be what we want to pull into a docs snippet though?

@patriknw

Copy link
Copy Markdown
Contributor

I think this is nice to have in a sample but too complex to put in docs though.
Not sure what a realistic example that is much simpler would be except the streaming view updates.

Not realistic, but easy to understand could be:

  @Get("/current-time")
  public HttpResponse streamCurrentTime() {
    var timeSource =
        Source.tick(Duration.ZERO, Duration.ofSeconds(5), "tick")
            .map(__ -> System.currentTimeMillis());

    return HttpResponses.serverSentEvents(timeSource);
  }

I don't understand why we should hold back on showing the more advanced, but realistic example? Nobody will find it in that sample and once again we have a cool feature that nobody knows about. It would be in the "Advanced HTTP requests and responses" so it's not like the first thing that will scare away people.

@johanandren

Copy link
Copy Markdown
Contributor Author

Ok, fair enough

@patriknw

Copy link
Copy Markdown
Contributor

Might even be good to first show the clock ticks and then say "a more realistic example would be..."

@aludwiko aludwiko left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nice to show that feature 👍

@patriknw patriknw left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Source<Customer, Cancellable> streamOfChanges = // <2>
stateEvery5Seconds.scan(new CustomerStreamState(Optional.empty(), true),
(state, newCustomer) ->
new CustomerStreamState(Optional.of(newCustomer), state.customer.isPresent() && state.customer.get().equals(newCustomer))

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

or

new CustomerStreamState(Optional.of(newCustomer), state.customer.equals(Option.of(newCustomer))

In my example I had made the first stateEvery5Seconds a Source<Option<Customer>

but not very important

@johanandren
johanandren merged commit ff42bf8 into main Feb 14, 2025
@johanandren
johanandren deleted the wip-sse-responses branch February 14, 2025 13:06
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation documentation related java-sdk

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants