State Structure Specification

Within Bacalhau, the State structure is designed to represent the status or state of an object (like a Job), coupled with a human-readable message for added context. Below is a breakdown of the structure:

State Parameters

1. StateType (T : <required>): Represents the current state of the object. This is a generic parameter that will take on a specific value from a set of defined state types for the object in question. For jobs, this will be one of the JobStateType values.

2. Message (string : <optional>): A human-readable message giving more context about the current state. Particularly useful for states like Failed to provide insight into the nature of any error.

Job State Types

When State is used for a job, the StateType can be one of the following:

1. Pending: This indicates that the job is submitted but is not yet scheduled for execution.

2. Running: The job is scheduled and is currently undergoing execution.

3. Completed: This state signifies that a job has successfully executed its task. Only applicable for batch jobs.

4. Failed: A state indicating that the job encountered errors and couldn't successfully complete.

5. JobStateTypeStopped: The job has been intentionally halted by the user before its natural completion.

The inclusion of the Message field can offer detailed insights, especially in states like Failed, aiding in error comprehension and debugging.

SpecConfig provides a unified structure to specify configurations for various components in Bacalhau, including engines, publishers, and input sources. Its flexible design allows seamless integration with multiple systems like Docker, WebAssembly (Wasm), AWS S3, and local directories, among others.

SpecConfig Parameters

• Type (string : <required>): Specifies the type of the configuration. Examples include docker and wasm for execution engines, S3 for input sources and publishers, etc.

• Params (map[string]any : <optional>): A set of key-value pairs that provide the specific configurations for the chosen type. The keys and values are flexible and depend on the Type. For instance, parameters for a Docker engine might include image name and version, while an S3 publisher would require configurations like the bucket name and AWS region. If not provided, it defaults to nil.

Usage Examples

Here are a few hypothetical examples to demonstrate how you might define SpecConfig for different components:

Docker Engine

Copy

{
  "Type": "docker",
  "Params": {
    "Image": "my_app_image",
    "Entrypoint": "my_app_entrypoint",
  }
}

Full Docker spec can be found here.

S3 Publisher

Copy

{
  "Type": "s3",
  "Params": {
    "Bucket": "my_bucket",
    "Region": "us-west-1"
  }
}

Full S3 Publisher can be found here.

Local Directory Input Source

Copy

{
  "Type": "localDirectory",
  "Params": {
    "SourcePath": "/path/to/local/directory",
    "ReadWrite": true,
  }
}

Full local source can be found here.

Remember, the exact keys and values in the Params map will vary depending on the specific requirements of the component being configured. Always refer to the individual component's documentation to understand the available parameters.