Capabilities

Use compose-capability to specify and request the grant of a CAPABILITY, which is an application of a 'defcap' production. This function is only valid within a (distinct) 'defcap' body. It is used as a way to compose CAPABILITY with the outer capability, such that the scope of the containing 'with-capability' call will "import" this capability.

Thus, a call to (with-capability (OUTER-CAP) OUTER-BODY), where the OUTER-CAP defcap calls (compose-capability (INNER-CAP)), will result in INNER-CAP being granted in the scope of OUTER-BODY.

To specify and request the grant of a CAPABILITY within a 'defcap' body, use the following syntax:

(compose-capability CAPABILITY)

Use the following argument to specify the CAPABILITY for the compose-capability Pact function.

The compose-capability function returns a boolean value to indicate success or failure in requesting the grant of the specified CAPABILITY.

The following example demonstrates the compose-capability function:

In this example, (compose-capability (TRANSFER src dest)) is used within a 'defcap' body to specify and request the grant of the TRANSFER capability with source src and destination dest. This would be used in the context of composing capabilities within a 'defcap' production and requesting grants in the scope of the containing 'with-capability' call.

Use emit-event to emit a specified CAPABILITY as an event without evaluating the body of the capability. This function fails if the CAPABILITY is not marked as @managed or @event.

To emit a CAPABILITY as an event without evaluating its body, use the following syntax:

(emit-event CAPABILITY)

Use the following argument to specify the CAPABILITY for the emit-event Pact function.

The emit-event function returns a boolean value indicating success or failure of emitting the event.

The following example demonstrates the emit-event function:

In this example, (emit-event (TRANSFER "Bob" "Alice" 12.0)) is used to emit the capability TRANSFER with parameters "Bob", "Alice", and 12.0 as an event. The function returns a boolean value indicating the success or failure of emitting the event.

Use install-capability to specify and provision the installation of a managed CAPABILITY. Managed capabilities are defined within a 'defcap' block, where a '@managed' tag designates a single parameter to be managed by a specified function. After installation, the CAPABILITY must still be brought into scope using 'with-capability', at which time the 'manager function' is invoked to validate the request.

The manager function is of type 'managed: requested: -> ', where '' indicates the type of the managed parameter. For example, if you have '(defcap FOO (bar:string baz:integer) @managed baz FOO-mgr ...)', the manager function would be '(defun FOO-mgr:integer (managed:integer requested:integer) ...)'.

Any capability matching the 'static' (non-managed) parameters will cause this function to be invoked with the current managed value and that of the requested capability. The function should perform whatever logic, presumably linear, to validate the request, and return the new managed value representing the 'balance' of the request.

Note that signatures scoped to a managed capability cause the capability to be automatically provisioned for installation similarly to one installed with this function.

To specify and provision the installation of a managed capability, use the following syntax:

(install-capability capability)

Use the following argument to specify the capability you want to install using the install-capability Pact function.

The install-capability function returns a boolean value indicating the success or failure of the installation, along with a string message providing additional information.

The following example demonstrates the use of install-capability in the Pact REPL to install a capability named PAY with specified parameters:

In this example, the capability named PAY with the provided parameters is installed. If successful, it returns a boolean value indicating success; otherwise, it returns an error message indicating the reason for failure.

The require-capability function specifies and tests for the existing grant of a specified CAPABILITY, failing if it is not found in the environment.

To specify and test for the existing grant of a CAPABILITY, use the following syntax:

(require-capability CAPABILITY)

Use the following argument to specify the CAPABILITY to be tested for its existing grant using the require-capability Pact function.

The require-capability function returns a boolean value indicating whether the specified CAPABILITY exists in the environment.

The following example demonstrates the usage of the require-capability function within a Pact script. It tests for the existing grant of the capability to transfer funds from one source to another:

This example illustrates how to use the require-capability function to check for the existing grant of a specific capability in the environment. If the capability is not found, the function will fail.

The with-capability function specifies and requests the grant of an acquired capability, which is an application of a 'defcap' production. It ensures that the specified unique token granted by this application is present in the environment during the execution of the provided body.

with-capability can only be called in the same module that declares the corresponding 'defcap'. If the token is not present, the capability is evaluated, and upon successful completion, the token is installed or granted in the environment. The token will be automatically revoked upon completion of the body. Nested with-capability calls for the same token detect the presence of the token and execute the body without reapplying the capability.

To specify and request the grant of an acquired CAPABILITY, use the following syntax:

(with-capability CAPABILITY BODY)

Use the following arguments to specify the capability and the body for execution using the with-capability Pact function.

The with-capability function returns the result of executing the provided body under the granted capability.

The following example demonstrates the usage of the with-capability function within a Pact script. It requests the grant of an 'UPDATE-USERS' capability and executes the body, updating user information:

This example illustrates how to use the with-capability function to ensure the execution of specific operations under the granted capability in Pact, providing a controlled access mechanism to sensitive functionalities.