App Marketplace

Documentation

Lifecycle Events

Overview

Application lifecycle events is a feature that allows vendors to add custom logic to their application that can be invoked by a Marketplace infrastructure automatically.

The focus of this feature is to enable scenario, when a marketplace application needs to perform some actions in a 3rd party api before it will be considered ready and start receiving calls from Socotra tenant. Or a scenario when app needs to perform a cleanup logic before being shut down.

Currently platform supports 2 lifecycle events - Start and Stop.

Start event is invoked after application starts and reported healthy, Stop event is invoked as a last event before application route is disabled and all resources used by app are released.

If lifecycle event handler in app fails to respond with successful response code or complete it’s work in an allocated time period - app instance will be set to an error state and no calls can reach this specific instance.

How to implement

To enable a specific lifecycle event app developer needs to implement a specific endpoint and update application manifest. For lifecycle events, Socotra platform reserves a specific path that will be used for all implemented and future lifecycle events - /_app/ so developers should not use this path in their application for any business functionality such as webhooks, autofill, external rater or other routes.

When lifecycle event triggers - Marketplace platform will send at least one GET request to a running application using it’s endpoint url. In a query string there will be route parameter which will contain a full endpoint URL as a value (so application handler can use it to integrate with external service).

For example, if an endpoint of a running application instance is https://12345abcde.sandbox.outpost.marketplace.socotra.com and Start event is enabled - marketplace platform will perform an equivalent of the following curl command (and router will add all necessary special headers):

curl --get "https://12345abcde.sandbox.outpost.marketplace.socotra.com/_app/start" \
   --data-urlencode "route=https://12345abcde.sandbox.outpost.marketplace.socotra.com"

Similarly, for Stop event - invoked URL will be https://12345abcde.sandbox.outpost.marketplace.socotra.com/_app/stop

This call will go through Marketplace routing service and will receive all necessary headers injections, such as x-smp-key header which can be used to retrieve app configuration set by customer, so the app can then use app configuration values to perform 3rd party API calls.

Note

Regardless of what response app will receive from 3rd party API calls, lifecycle events cannot be used to modify application own settings or state. So it’s impossible for 3rd party API to alter any customer-configured values of this app instance or inject new values into configuration.

Start/Stop

Start event is triggered after application started in a cluster and cluster performed a successful health check of a running container. At this point underlying infrastructure assigned a routable port to an app and registered app route with a public router.

NOTE - Your app is now reachable from the public internet via its URL

Start event occurs before our automatic registration event for webhooks, autofill and externalRater settings (if those sections are configured in socotra-app manifest).

Stop event is a last event that is triggered in the pipeline before application resources unallocated and app instance is shut down. Stop event occurs after our automatic deregistration event for webhooks, autofill and externalRater settings.

For more details - see illustration in "System behavior" section below.

Manifest changes

Developer can use app-manifest generator from our marketplace portal or manually configure corresponding events in `socotra-app.json`` manifest file.

To manually configure lifecycle event trigger, add or update the "lifecycle" section in the manifest file. It's a child section for "socotra" object with value set to array of strings, allowed array values are "start" to enable lifecycle start event and "stop" to enable corresponding stop event:

{
  "socotra": {
    "lifecycle": ["start", "stop"]
  }
}

Lifecycle endpoints

Developer needs to implement an endpoint which will receive start or stop event call, it must be configured at one of the following paths

/_app/start - for Start lifecycle event

/_app/stop - for Stop lifecycle event.

and support route query string parameter.

NOTE - Endpoint must complete all it’s work under 1 minute timeout and return 200 OK or 201 Created status code.

If application fails to perform all the work in 1 minute - platform request will timeout (even if app will eventually complete this request successfully) and application instance will be set to Error state.

For Start event this means - no other integrations will be performed and application will not be functional until it will be reconfigured again and start event will complete successfully.

For Stop request this will be reflected in logs and application resources will be freed and app will be stopped regardless of lifecycle processing outcomes. As well as de-allocation of the resources will be triggered as soon as endpoint returns the status code or times out after 1 minute.