Applicatin Lifecycle states

This is a lifecycle of an app instance after it being configured.

When customer configuration is saved, FE sends a Start command to an app instance automatically. When app is running and customer clicks Stop - corresponding command sent to an app instance.

During these phases app state transitioning in the following order

Start command State created as Pending Allocation command - can transition to Error if allocation fails Lifecycle Start - Transitions to Starting in the beginning

• If successful start event - No change
• If error -> transition to Error state Register command
• Transitions to Registering in the beginning
• Transitions to Running after registrations completed

Start command

When platform receives Start command, it verifies the request and issues Allocate command which instructs cluster to allocate requested resources and run app docker container image with those resources.

After docker image downloaded, launched in a cluster and indicated that the instance is healthy (responded to /health endpoint with 200 OK code), Platform will issue a LifecycleStart message.

In response to it, system will verify existence of a healthy app instance and fetch the public endpoint URL (e.g. abc123.sandbox.outpost.marketplace.socotra.com).

Then it will send a GET request to this address, passing public endpoint as a query string parameter: https://abc123.sandbox.outpost.marketplace.socotra.com/_app/start?route=https%3a%2f%2fabc123.sandbox.outpost.marketplace.socotra.com

If application responds with 2xx status code within 1 minute time frame - LifecycleStart event considered completed successfully and system will continue with Register message which will register all configured webhooks autofills and external raters in customer’s tenant.

If application fails to respond with 2xx status code or response took longer than 1 minute - Application status will be set to `Error``, corresponding log entry will be written to app instance logs and no further registrations will be performed. At this point app instance is marked as failed and it must not be used any further until customer update the configuration of the app or vendor would upload a new version of the app which handles lifecycle correctly (customer would need to switch configuration to use new version of the app in this case).

Stop command

When platform receives Stop command for a running app instance, it will first queue Deregister command which will cleanup all existing integrations (webhooks, autofill, externalRaters) between this app instance and configured socotra tenant. Then it will issue a LifecycleStop message.

In response to it system will perform a GET request to corresponding app url, e.g. https://abc123.sandbox.outpost.marketplace.socotra.com/_app/stop?route=https%3a%2f%2fabc123.sandbox.outpost.marketplace.socotra.com and will allow up to 1 minute for the app to process this event and cleanup integrations in 3rd party services.

If app processing of LifecycleStop succeeds and return 2xx status code within 1 minute - Platform will continue with Release command which will de-allocate app resources in the cluster and set app instance to Stopped state.

If app fails to return `2xx`` status code or takes longer than 1 minute to process the command - Platform will set app instance state to Error and will continue with resource de-allocation.

Lifecycle endpoints

Idempotency of /_app/start and /_app/stop handlers

Due to the asynchronous and distributed nature of our message processing platform, we can’t give 100% guarantee that Start or Stop endpoints will be called “Exactly Once”.

“At least once" delivery is our best theoretically possible mode, which means that in rare occurences we may send `GET`` calls to app instance more than once.

Vendors need to accommodate for such scenarios and handle it correctly:

• If app receives more than one Start or Stop call - it must not return any errors for consequent calls if processing of the first call was successful.
• If processing of first call failed\timed out - consequent calls must return same failure response and should not change it to success.