Proposed Subscription Design Change

Background

In the fall of 2018, we modified the HAPI-FHIR Server Subscription functionality to add support for running subscription processing in a separate server from the REST server. This happened in stages:

In-memory matcher added a new class SubscriptionMatcherInMemory that matches incoming resources against subscription criteria by examining the content within the resource directly rather than querying the database.

Standalone subscription added a new maven module called hapi-fhir-jpaserver-subscription and moved classes there from hapi-fhir-jpaserver-base so that the SubscriptionMatcherInMemory had everything it needed to match resources against subscription criteria without access to a database. Classes needed by both hapi-fhir-jpaserver-subscription and hapi-fhir-jpaserver-base were moved into two new maven modules called hapi-fhir-jpaserver-model and hapi-fhir-jpaserver-searchparam.

One final change remains in order to be able to process subscription outside of the REST server: maintaining an in-memory cache of active subscriptions.

For simplicity, I don't cover the DELETE case below. Assume that DELETE undos whatever the CREATE did.

Requirements

Four things need to happen when a new subscription arrives on the REST server:

1. Validate the criteria on the subscription and reject it if the criteria are invalid.
2. Activate the subscription (that is change the status of the subscription from REQUESTED to ACTIVE)
3. Add the subscription to an in-memory cache of active subscriptions that future resources are matched against.
4. Create a new Delivery Queue and DeliveryHandler. Matching resources will be sent to that queue and sent to the end point by the DeliveryHandler. The DeliveryHandler will perform the action specified in the subscription, e.g. e.g. send an e-mail, make a REST call, etc.

How it works today

Currently, all of four of these functions are managed within HAPI-FHIR Interceptors. Most of the functionality resides within the abstract class BaseSubscriptionInterceptor. There are subclasses of this for each type of subscription: SubscriptionRestHookInterceptor, SubscriptionEmailInterceptor etc... When the HAPI-FHIR JPA Server starts up, subscription processing functionality is added to it by enabling one or more of these interceptors.

Interceptor startup

When the interceptor starts up, it creates the following objects that it stores internally within itself:

1. A Processing Queue for processing incoming resources
2. SubscriptionActivatingSubscriber responsible for extra processing on incoming subscriptions
3. Three subscription caches: active subscriptions, subscription channels, and delivery handlers
4. A SubscriptionCheckingSubscriber responsible for matching incoming resources against cached subscriptions

Then at startup, the Interceptor reads the database and for each subscription of this interceptor type, it performs the "Subscription arrives" operation described below.

Effectively there are multiple subscription caches--one for each type of interceptor. Further, only subscriptions for which there is a registered interceptor, will be activated. (e.g. if there is an EmailInterceptor and a RestHook subscription arrives, it won't be activated.) This subscription-type based activation, helps inform end-users which kinds of subscriptions are supported by this server.

Subscription arrives

This is the extra processing that the SubscriptionActivatingSubscriber does on incoming subscription resources:

1. Validate the criteria, and reject the CREATE/UPDATE if it's invalid.
2. Ignore subscriptions not of the type of this interceptor (e.g. email subscriptions ignored by rest interceptor)
3. If the subscription is REQUESTED, change it to ACTIVE and send it back the interceptor to be processed a second time.
4. If the subscription is ACTIVE, create a Delivery Queue and a DeliveryHandler (the interceptor knows what kind of handler to create) and populate the three subscription hashes in the interceptor.

Resource arrives

When a resource arrives, it is sent to each type of interceptor. Each interceptor does the following:

1. Submit the resource to the Processing Queue
2. Then in a separate thread, the SubscriptionCheckingSubscriber for this interceptor pulls the resource from the Processing Queue and does the following.
3. Loop through all the subscriptions in that Interceptor's cache and check if the resource matches it.
4. If the resource matches, it sends it to the Delivery Queue belonging to that subscription.
5. The DeliveryHandler then pulls it from the Delivery Queue and sends it out as e-mail, a rest call, etc.

Proposed Redesign

In a configuration where subscription matching happens in a separate server from the REST server, it will work as follows. The following process below assumes that all resources successfully processed by the FHIR-Server are also sent to the Subscription Server. The process of how resources are sent to the Subscription Server is not covered here.

FHIR-Server and Subscription Server Configuration

Both the FHIR Server and the Subscription Server will have a new configuration attribute that contains a list of Subscription types supported by this cluster of FHIR servers.

FHIR-Server Startup

A new SubscriptionActivatingInterceptor at startup activates any supported subscriptions in the database that need to be activated. It then processes subscription resources as described below.

Subscription Server Startup

A new SubscriptionRegistry will maintain 3 caches for all supported subscriptions (active subscription, delivery queue, delivery handler). When it starts up, it loads the caches with all supported subscriptions. (There are no longer separate caches for each type).

Subscription arrives on FHIR-Server

1. SubscriptionActivatingInterceptor validates the criteria, and reject the CREATE/UPDATE if it's invalid.
2. If the subscription is REQUESTED, change it to ACTIVE and send it back to itself to be processed a second time.

Subscription arrives at Subscription Server

1. If the subscription not ACTIVE, ignore it.
2. Otherwise, the SubscriptionRegistry creates a Delivery Queue and a DeliveryHandler based on the type of Subscription (e.g. an email DeliveryHandler for eMail subscriptions) and populates its three subscription hashes.

Resource arrives at Subscription Server

1. Loop through all the subscriptions in the SubscriptionRegistry cache and check if the resource matches it.
2. If the resource matches, it sends it to the Delivery Queue belonging to that subscription.
3. The DeliveryHandler then pulls it from the Delivery Queue and sends it out as e-mail, a rest call, etc.

Backwards compatibility

In the case where the FHIR Server and the Subscription server are on the same server, it will still work in this new way. The main differences are that:

1. The new config parameter is used to determine which types of subscriptions are supported (rather than the presence of an interceptor of that type)
2. All subscriptions will be looped over in one thread rather than the looping happening in different threads for different subscription types.