Containers
Workspaces - Stoping and resuming

Sphere Engine Containers module offers a convenient feature that allows workspaces to be stopped and then resumed, preserving their exact state. This means that tasks initiated in one session can seamlessly continue in subsequent ones, eliminating the requirement to save ongoing progress on the end-user's device.

This feature has numerous impactful applications. For instance:

• for complex software projects that require multiple sessions due to their advanced nature,
• projects intended as a foundation for a series of interrelated classes,
• tasks started in educational settings, allowing for completion at home or the addition of further assignments as homework,
• recruitment projects undertaken by candidates, which can be paused and later resumed during live interviews.

All these use-cases share the same ability of returning to work that was started in the past.

The ability to stop and resume a workspace is not enabled by default and requires conscious use, namely:

• the feature should be enabled during workspace creation (read on),
• the configuration of the workspace lifespan should not conflict with the configuration of the stop/resume mechanism (read on),
• the workspace stops: (read on):
  • when it was inactive or abandoned,
  • manually via API or through the customer panel,
• a stopped workspace retains its data but it's inactive, which means that occupied resources (i.e., "slots") are released and can be used elsewhere,
• the workspace resumes to work by any of the following actions (read on):
  • the end user re-enters to it,
  • manually via API.

The following diagram presents the life-cycle of the workspace assuming using stop/restore functionality. It shows the different states and the transitions between them.

Creating a stoppable workspace

As stated before, by default the stop/resume feature for a new workspace is disabled. To enable it, a workspace needs to be initialized using the workspace creation API method with a proper set of parameters:

• primary retention_time_stopped - the retention time of the stopped container (in minutes),
  • a default value of 0 means that the workspace cannot be stopped (i.e., the feature is disabled),
  • a value greater than 0 enables the stop/resume feature,
  • the retention timer resets with every restore,
  • if the workspace is not restored after defined time, it is removed,
• secondary retention_time_total - the maximum time after which the workspace will be unconditionally removed (in minutes),
  • this value does not reset, after specified time the workspace will be removed regardless it is stopped or actively used,
  • this value should be big enough to keep workspace active or restorable as long as required,
• secondary inactivity_timeout - the time after the abandoned or inactive workspace is stopped or removed (in minutes),
  • if the value of retention_time_stopped is greater than 0, then the workspace is stopped,
  • otherwise, it is removed.

Read on below for more details about workspace parameters related to the stop/resume feature.

The curl command below presents how to start the workspace with the stop/resume feature enabled using Sphere Engine Containers API:

curl -X POST \
  -F "project_id=<project_id>" \
  -F "retention_time_stopped=1500" \
  -F "retention_time_total=10080" \
  -F "inactivity_timeout=15" \
  "https://<customer_id>.containers.sphere-engine.com/api/v1/workspaces?access_token=<access_token>"

In this example setting the retention_time_stopped parameter to a value of 1500 (i.e., 60 * 25 minutes) allows the workspace to be stopped for up to 25 hours. In case of exceeding this time, the workspace will be removed. However, if the workspace is restored within the period of 25 hours and then once again stopped, the counter resets and another 25 hours are counted down.

The value of the retention_time_total parameter is equal to 10080 which is 60 * 24 * 7 minutes, a one week. This is the hard limit for the workspace to exist. After exceeding this time, it will be unconditionally removed regardless its current state and other settings.

The final parameter, inactivity_timeout, is set to 15 minutes. If there has been no activity within the workspace for this duration or if it has been abandoned (e.g., by closing the associated web browser tab), the workspace will be automatically stopped.

Stopping the workspace

The workspace stops in the following cases:

• after being inactive for some time (even if it remains open in an active web browser tab),
• after being abandoned and remaining inactive for a period of time (e.g., by closing the associated web browser tab),
• manually via API by using the stop workspace API method,
• through the customer panel here by clicking the stop button in the Actions column.

The curl command provided below stops the workspace specified by the id parameter.

curl -X PUT "https://<customer_id>.containers.sphere-engine.com/api/v1/workspaces/<id>/stop?access_token=<access_token>"

Resuming the workspace

To resume the workspace, one can execute any of the following actions:

• re-enter the workspace using the original link,
• use the resume workspace, API method.

The curl command provided below resumes the workspace specified by the id parameter.

curl -X PUT "https://<customer_id>.containers.sphere-engine.com/api/v1/workspaces/<id>/resume?access_token=<access_token>"

Involved workspace parameters

As already discussed, there are three parameters of the workspace that affect the behavior of the stop/restore mechanism:

• retention_time_stopped - the maximum time for which the stopped workspace will be stored,
• retention_time_total - the maximum time after which the workspace will be unconditionally removed,
• inactivity_timeout - the time after which the inactive or abandon workspace will be either stopped or removed.

These parameters exhibit mutual dependence, a topic further explored in the consecutive subsections below.

Parameter retention_time_stopped

This parameter stands as the linchpin of the stoping/restoring mechanism, giving rise to the subsequent considerations:

• by intention, it defines the maximum time for which the workspace will be stored as stopped,
  • yet, it doesn't work without a compatible retention_time_total value in parallel,
  • if the value of retention_time_total is too low, the stopped workspace will be removed or it can even live not long enough to be stopped,
• the time for which the stopped workspace will be kept resets every time the workspace is resumed,
  • for example if the value is set to be 25 hours, then the end-user can come back to the workspace daily roughly at the same time to reset the counter and keep the workspace accessible,
• the workspace that is inactive or abandoned for the time defined by the inactivity_timeout parameter is automatically stopped.

Parameter retention_time_total

This parameter serves as a secondary yet important component of the stop/restore mechanism. It determines the maximum total lifespan of workspaces within the Sphere Engine Containers module. Upon reaching this defined duration, the workspace is automatically removed. This rule is unconditional, applicable to both actively working and stopped workspaces.

Parameter inactivity_timeout

This parameter specifies the duration after which an inactive or abandoned workspace will either be stopped or removed:

• the workspace is considered abandoned if its user interface is no longer displayed anywhere, for instance, after closing the web browser tab where it was active,
• the workspace is deemed inactive if no actions are performed inside it for the defined duration,
• if the value of the retention_time_stopped parameter is greater than 0, the workspace is stopped, allowing for potential later restoration,
• otherwise, it is removed without the possibility of recovery.