Quarkus - Pusher Beams

This extension brings the Pusher Push Notification Server java library into the Quarkus ecosystem and supports both JVM and Native modes.

Features

The extension provide the same features as the original Pusher library. For more information about it, please refers to the Pusher Java/Kotlin documentation

The extension also provides the following additional features.

CDI injection

You can inject the BeamsClient in your application & use it to interact with your Pusher Beams instance.

Retry on HTTP 429 responses from Pusher

As you may know, Pusher has rate limits on its services. The rate limit will depends on your subscription model.

As the BeamsClient wrap the call to the Pusher SDK, it also catch any PusherTooManyRequestsError returned and will automatically sleep for a configurable delay and try to re-submit your request again. It will do that until either the request could be successfully submitted, or another critical error is returned / thrown by the SDK, or the number of retry exceed the maximum number of attempts configured on the extension.

To customize this retry behavior, please refers to the configuration section below.

Support

• Pusher Beams server SDK version 1.1.1

How to install

The quarkus-pusher-beams jar is available in Maven Central.

<dependencies>
    <dependency>
      <groupId>io.quarkiverse.pusher.beams</groupId>
      <artifactId>quarkus-pusher-beams</artifactId>
      <version>1.0.1</version>
    </dependency>
</dependencies>

How to configure

Enabling / disabling the extension

The extension is enabled by default as long as you include it into your dependencies. To disable it through configuration, please use the following property.

Optional

Defaults to true.

quarkus.pusher.beams.enabled=false

Configure Pusher Beams instance ID

Set the Pusher Beams instance ID to connect to.

Required

quarkus.pusher.beams.instance-id=8f9a6e22-2483-49aa-8552-125f1a4c5781

Configure Pusher Beams instance secret key

Set the Pusher Beams instance secret key to connect to.

Required

quarkus.pusher.beams.secret-key=C54D42FB7CD2D408DDB22D7A0166F1D

Configure rate limit behavior - maximum retry

Configures the maximum number of attempt the extension will try to re-submit your Pusher operation (i.e publish to users, delete a user, etc.) in case of PusherTooManyRequestError.

Optional

Default value is 5.

quarkus.pusher.beams.rate-limit.max-retry=3

Configure rate limit behavior - delay

Configures the delay in milliseconds between attempts in case of PusherTooManyRequestError.

Optional

Default value is 20 milliseconds.

quarkus.pusher.beams.rate-limit.delay=100

How to use

Publish to users (Apple)

Here is an example to publish to users using the PublishRequest bean. The publishToUsers function explicitly throw some exceptions that you'll have to handle but be aware that the Pusher SDK also thrown several runtime exceptions that you may be interested in handling as well depending on your use case.

@ApplicationScoped
public class AppleNotificationExample {

  @Inject
  BeamsClient beamsClient;
  
  public void publish(final List<String> users, final String title, final String subtitle, final String body) {
  
    // Use the PublishRequest object or build your own custom Map as publish request
    final PublishRequest publishRequest = new PublishRequest();
    publishRequest.apns()
                .aps()
                .withBadge(1)
                .withMutableContent();
    publishRequest.apns()
                .aps()
                .alert()
                .withTitle(title)
                .withSubtitle(subtitle)
                .withBody(StringEscapeUtils.unescapeJava(body));
    publishRequest.apns()
                .pusher()
                .withDisableDeliveryTracking();
    
    try {
    
      beamsClient.publishToUsers(users, publishRequest);
      
    } catch (IOException | InterruptedException | URISyntaxException e) {
    
      // Unexpected exception handling here
      
    } catch (PusherAuthError | PusherTooManyRequestsError | PusherMissingInstanceError | PusherValidationError | PusherServerError e) {
    
      // Pusher runtime exception handling here
    }
  }
}

Delete a user

Here is an example to delete a user. The deleteUser function does not explicitly throw any exception but be aware that the Pusher SDK also thrown several runtime exceptions that you may be interested in handling as well depending on your use case.

@ApplicationScoped
public class DeleteUserExample {

  @Inject
  BeamsClient beamsClient;
  
  public void delete(final String userId) {
  
    try {
    
      beamsClient.deleteUser(userId);
      
    } catch (PusherAuthError | PusherTooManyRequestsError | PusherMissingInstanceError | PusherValidationError | PusherServerError e) {
    
      // Pusher runtime exception handling here
    }
  }
}

Generate a token

Here is an example to generate a token.

@ApplicationScoped
public class GenerateTokenExample {

  @Inject
  BeamsClient beamsClient;
  
  public void generate(final String userId) {
  
      Map<String, Object> tokenInfo = beamsClient.generateToken(userId);
      
      // Do anything you need with token information
      // Usually this is used on your own authentication endpoint to authenticate Pusher beams users.
  }
}

How to contribute to this extension

This extension should provide all you need to interact with your Pusher Beams instance and use the Pusher Beam server SDK.

But if you notice anything wrong, want to submit additional features or cover more things inside the existing features, please submit your remarks and/or PR.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

nvivot 💻 🚧

This project follows the all-contributors specification. Contributions of any kind welcome!