A transactional plug to manage internal state safely.
CAF goal is to create and manage billions of long running, active, stateful proxies, i.e., CAs, where "long running" means years. In order to tolerate -without human intervention- failures, upgrades, migration, or other errors, the CA state has to be managed carefully.
A complication is that CA state is not only application state, but state associated with the plugins that the application uses.
Also, CAF always ensures that CA state is consistent with the externalized view of that state, i.e., CA actions that affect the external world.
For example, if a CA sends a message, and it keeps track of sent messages in its internal state, even in the presence of failures it should never forget that it sent that message.
CAF approach assumes:
-
Operations that affect the external world are mediated by a plugin that makes them idempotent.
-
Plugins defer these operations until commit time, ensuring that, before execution, a persistent record of them has been checkpointed to an external service.
-
All plugins and application code coordinate using a two-phase commit protocol, so that disaggregated state is managed consistently.
-
During recovery the last committed state is reloaded, and deferred operations in the checkpoint are retried until they succeed.
Methods __ca_setLogActionsTarget__ and __ca_lazyApply__ defer methods.
Methods __ca_init__ and __ca_resume__ handle initialization and
recovery.
Methods __ca_begin__, __ca_prepare__, __ca_commit__ and __ca_abort__
implement the two-phase commit protocol.
Variable that.state is a JSON-serializable representation of this plugin
state. The contents of this variable are always checkpointed before
any state externalization, unless it is null.
- Source:
Extends
Members
__ca_isTransactional__ :boolean
- Source:
Run-time type information.
Type:
- boolean
Methods
(static) create($, spec) → {Object}
- Source:
Helper constructor method for a transactional component.
Description of types in file types.js.
Parameters:
| Name | Type | Description |
|---|---|---|
$ |
ctxType | A context containing references to other components. |
spec |
specType | Configuration data for this component. |
Throws:
-
If inputs are invalid.
- Type
- Error
Returns:
A new generic component.
- Type
- Object
__ca_abort__(cb)
- Source:
Aborts the transaction.
CAF calls this method when an error was returned
by the handler, or any transactional plugs propagated an error during
prepare.
Note that an error during remote checkpointing cannot guarantee that the checkpoint was not made durable, and we need to assume that it did. This means that we need to shutdown the CA.
An implementation of this method should undo state changes and ignore deferred operations.
Parameters:
| Name | Type | Description |
|---|---|---|
cb |
cbType | A callback to continue after aborting. |
__ca_begin__(msg, cb)
- Source:
Begins a two phase commit transaction.
CAF calls this method before the application handler processes a message. A read-only copy of the message is passed as an argument to facilitate configuration.
Parameters:
| Name | Type | Description |
|---|---|---|
msg |
Object | The message to be processed. |
cb |
cbType | A callback to continue the transaction. |
__ca_commit__(cb)
- Source:
Commits the transaction.
Called by CAF when all the prepare calls to transactional
plugs were successful, and the new state of those plugs has been
checkpointed using an external service.
An error during commit will shutdown the CA since we cannot abort
committed transactions. See __ca_resume__ for the recovery strategy.
Parameters:
| Name | Type | Description |
|---|---|---|
cb |
cbType | A callback to continue after commiting. |
__ca_init__(cb)
- Source:
Initializes the state of this plug from scratch.
This method is called only once, when the plug is created.
Parameters:
| Name | Type | Description |
|---|---|---|
cb |
cbType | A callback to continue after initialization. |
__ca_lazyApply__(method, args)
- Source:
Queues an operation to be executed at commit time.
Internally, operations are made asynchronous and executed serially by
adding an extra callback. The actual implementation of these operations
is delegated to the logActionsTarget object.
Operations are assumed to be idempotent.
Parameters:
| Name | Type | Description |
|---|---|---|
method |
string | A method name to execute. |
args |
Array.<any> | An array of method arguments. |
__ca_prepare__(cb)
- Source:
Prepares to commit the transaction.
CAF calls this method after the handler has succesfully processed the message.
If ready to commit, it returns in the callback a JSON serializable data structure reflecting the new state after processing the message.
Then, CAF checkpoints this data structure using a remote service.
To abort the transaction we return an error in the (node.js) callback. This will abort all the transactional plugs associated with the CA.
Parameters:
| Name | Type | Description |
|---|---|---|
cb |
cbType | A callback to continue or abort the transaction. |
__ca_resume__(cp, cb)
- Source:
Reloads the state of this plug from a previous checkpoint.
It also retries deferred operations in the checkpoint.
This method is called many times, for example, after recovering from a failure or restarting after migration.
Parameters:
| Name | Type | Description |
|---|---|---|
cp |
Object | The last checkpoint of the state of this plug. |
cb |
cbType | A callback to continue after resuming. |
__ca_setLogActionsTarget__(obj)
- Source:
Sets a receiver object implementing all the delayed methods.
Parameters:
| Name | Type | Description |
|---|---|---|
obj |
Object | A receiver for delayed methods. |