Initialize the actor

Called when the actor is first started or restarted. This function is responsible for setting up the actor's initial state and responding to initialization parameters.

Parameters

• state - Current state of the actor, or None if first initialization
• params - Tuple of initialization parameters, typically including actor ID

Returns

• Ok((state,)) - The updated state to store
• Err(string) - An error message if initialization fails

Implementation Notes

• If state is None, the actor should create a new initial state
• If state contains data, the actor should validate and use that state
• The first parameter in the tuple is typically the actor's ID
• Any error returned will cause the actor to fail to start

Get a specific environment variable Returns None if the variable doesn't exist or access is denied

List all accessible environment variables Returns empty list if list_all is not enabled in config

Check if a specific environment variable exists (and is accessible)

Start a new OS process

Write to the standard input of a process

Get the status of a process

Send a signal to a process

Terminate a process

Process output event

Process error output event

Process exit event

Create a new store

Creates a new content-addressable store instance.

Returns

• Ok(string) - The ID of the newly created store
• Err(string) - Error message if store creation fails

Example

use ntwk::theater::store;

// Create a new store
let store_id = store::new()?;

Implementation Notes

Each actor has access to its own isolated store instances. Store IDs are only valid within the context of the actor that created them.

Store content

Stores content in the content-addressable store and returns a reference to it.

Parameters

• store-id - ID of the store to use
• content - The content bytes to store

Returns

• Ok(content-ref) - Reference to the stored content
• Err(string) - Error message if storage fails

Example

use ntwk::theater::store;

// Store some content
let data = serde_json::to_vec(&my_data)?;
let content_ref = store::store(store_id, data)?;

Implementation Notes

If identical content already exists in the store, the existing content reference will be returned without storing a duplicate copy.

Retrieve content

Retrieves content from the store using its content reference.

Parameters

• store-id - ID of the store to use
• content-ref - Reference to the content to retrieve

Returns

• Ok(list<u8>) - The retrieved content bytes
• Err(string) - Error message if retrieval fails

Example

use ntwk::theater::store;

// Retrieve content
let content = store::get(store_id, content_ref)?;
let my_data: MyData = serde_json::from_slice(&content)?;

Check if content exists

Checks if a particular content reference exists in the store.

Parameters

• store-id - ID of the store to check
• content-ref - Reference to check for

Returns

• Ok(bool) - True if the content exists, false otherwise
• Err(string) - Error message if the check fails

Example

use ntwk::theater::store;

// Check if content exists before attempting to retrieve it
if store::exists(store_id, content_ref)? {
let content = store::get(store_id, content_ref)?;
// Process content...
} else {
// Handle missing content case
}

Attach a label to content

Associates a human-readable label with a content reference.

Parameters

• store-id - ID of the store to use
• label - The human-readable label to attach
• content-ref - Reference to the content to label

Returns

• Ok(_) - Label was successfully attached
• Err(string) - Error message if labeling fails

Example

use ntwk::theater::store;

// Store and label config data
let config_data = serde_json::to_vec(&my_config)?;
let ref = store::store(store_id, config_data)?;
store::label(store_id, "current-config", ref)?;

Implementation Notes

A label can point to multiple content references, effectively acting as a collection. Each call to this function adds the content reference to the label without removing previous references.

Get content reference by label

Retrieves a content reference associated with a label.

Parameters

• store-id - ID of the store to use
• label - The label to look up

Returns

• Ok(option<content-ref>) - The content reference if found, None if the label doesn't exist
• Err(string) - Error message if the lookup fails

Example

use ntwk::theater::store;

// Retrieve the current configuration
if let Some(ref) = store::get_by_label(store_id, "current-config")? {
let config_data = store::get(store_id, ref)?;
let config: MyConfig = serde_json::from_slice(&config_data)?;
// Use configuration...
} else {
// No configuration found
}

Implementation Notes

If a label points to multiple content references, this function returns the most recently added reference.

Remove a label

Deletes a label and its associations with content references.

Parameters

• store-id - ID of the store to use
• label - The label to remove

Returns

• Ok(_) - Label was successfully removed
• Err(string) - Error message if removal fails

Example

use ntwk::theater::store;

// Remove an obsolete label
store::remove_label(store_id, "old-config")?;

Implementation Notes

Removing a label does not delete the content it points to, only the association between the label and the content references.

Remove a specific content reference from a label

Removes the association between a label and a specific content reference.

Parameters

• store-id - ID of the store to use
• label - The label to modify
• content-ref - The content reference to remove from the label

Returns

• Ok(_) - Reference was successfully removed from the label
• Err(string) - Error message if removal fails

Example

use ntwk::theater::store;

// Remove a specific version from the "historical-configs" label
store::remove_from_label(store_id, "historical-configs", outdated_ref)?;

Implementation Notes

This operation only removes the association between the label and the content reference. It does not delete the content itself.

Store content and immediately label it

Stores content and associates it with a label in a single operation.

Parameters

• store-id - ID of the store to use
• label - The label to attach to the content
• content - The content bytes to store

Returns

• Ok(content-ref) - Reference to the stored content
• Err(string) - Error message if the operation fails

Example

use ntwk::theater::store;

// Store and label user data in one operation
let user_data = serde_json::to_vec(&user)?;
let ref = store::store_at_label(store_id, "user-profile", user_data)?;

Implementation Notes

This is a convenience function that combines store and label operations. The label will point to the new content reference in addition to any existing content references it may already point to.

Replace content at a label

Stores new content and makes the label point exclusively to it, removing any previous associations.

Parameters

• store-id - ID of the store to use
• label - The label to update
• content - The new content bytes to store

Returns

• Ok(content-ref) - Reference to the stored content
• Err(string) - Error message if the operation fails

Example

use ntwk::theater::store;

// Update configuration with new values
let new_config = serde_json::to_vec(&updated_config)?;
let ref = store::replace_content_at_label(store_id, "current-config", new_config)?;

Implementation Notes

This operation is atomic - the label will either point to the new content reference or remain unchanged if the operation fails.

Replace label with specific content reference

Updates a label to point exclusively to an existing content reference.

Parameters

• store-id - ID of the store to use
• label - The label to update
• content-ref - The content reference the label should point to

Returns

• Ok(_) - Label was successfully updated
• Err(string) - Error message if the update fails

Example

use ntwk::theater::store;

// Revert to a previous version
store::replace_at_label(store_id, "current-config", previous_version_ref)?;

Implementation Notes

This operation removes any existing associations between the label and other content references. After this operation, the label will point only to the specified content reference.

List all labels

Retrieves a list of all labels in the store.

Parameters

• store-id - ID of the store to query

Returns

• Ok(list<string>) - List of all labels in the store
• Err(string) - Error message if the operation fails

Example

use ntwk::theater::store;

// Get all available labels
let labels = store::list_labels(store_id)?;
for label in labels {
println!("Found label: {}", label);
}

List all content references

Retrieves a list of all content references in the store.

Parameters

• store-id - ID of the store to query

Returns

• Ok(list<content-ref>) - List of all content references in the store
• Err(string) - Error message if the operation fails

Example

use ntwk::theater::store;

// Get all content references
let refs = store::list_all_content(store_id)?;
println!("Store contains {} content items", refs.len());

Implementation Notes

This operation may be expensive for stores with a large amount of content. Consider using labels to organize and access content more efficiently.

Calculate total size

Calculates the total size of all content in the store.

Parameters

• store-id - ID of the store to query

Returns

• Ok(u64) - Total size in bytes
• Err(string) - Error message if the calculation fails

Example

use ntwk::theater::store;

// Check store size
let total_bytes = store::calculate_total_size(store_id)?;
println!("Store contains {} bytes of data", total_bytes);

// Format as human-readable size
let size_mb = total_bytes as f64 / (1024.0 * 1024.0);
println!("Store size: {:.2} MB", size_mb);

Implementation Notes

This operation calculates the actual storage space used, accounting for deduplication of identical content.

Get current time

Returns the current time in milliseconds since the UNIX epoch (January 1, 1970 UTC).

Returns

The current timestamp in milliseconds

Example

use ntwk::theater::timing;

// Get current timestamp
let now = timing::now();

// Convert to seconds
let seconds_since_epoch = now / 1000;

Implementation Notes

The time value is consistent across the entire Theater runtime, ensuring that all actors have a synchronized view of time.

Pause execution

Pauses the execution of the actor for the specified number of milliseconds.

Parameters

• duration - Number of milliseconds to sleep

Returns

• Ok(_) - Sleep completed successfully
• Err(string) - Error message if sleep was interrupted or not allowed

Example

use ntwk::theater::timing;

// Sleep for 1 second
timing::sleep(1000)?;

// Sleep for 100ms
timing::sleep(100)?;

Security

The runtime may enforce limits on how long an actor can sleep to prevent resource exhaustion or denial of service. Sleep operations are recorded in the actor's event chain.

Wait until specific time

Pauses execution until the specified timestamp is reached.

Parameters

• timestamp - Target time in milliseconds since UNIX epoch

Returns

• Ok(_) - Deadline was reached successfully
• Err(string) - Error message if the wait was interrupted or not allowed

Example

use ntwk::theater::timing;

// Wait until a specific time
let target_time = 1672531200000; // Jan 1, 2023 00:00:00 UTC
timing::deadline(target_time)?;

// Wait until 10 seconds from now
let now = timing::now();
let ten_seconds_later = now + 10000;
timing::deadline(ten_seconds_later)?;

Implementation Notes

• If the specified timestamp is in the past, the function returns immediately
• The runtime may reject excessive deadline values that are too far in the future
• Deadline operations are recorded in the actor's event chain

Handle one-way message

Processes a one-way message that doesn't require a response.

Parameters

• state - The current actor state or None if not initialized
• params - Tuple containing:
• json - The message payload

Returns

• Ok((option<list<u8>>,)) - Updated actor state (or None to retain current state)
• Err(string) - Error message if message handling fails

Example

fn handle_send(state: Option<Value>, params: (Value,)) -> Result<(Option<Value>,), String> {
let (message,) = params;

// Process the message...

// Return updated state (or None to keep current state)
Ok((Some(updated_state),))
}

Handle request-response message

Processes a request that requires a response.

Parameters

• state - The current actor state or None if not initialized
• params - Tuple containing:
• string - The request ID
• json - The request payload

Returns

• Ok((option<list<u8>>, (option<list<u8>>,))) - Tuple containing:
• Updated actor state (or None)
• Response message to send back (or None to send a response yet)
• Err(string) - Error message if request handling fails

Example

fn handle_request(state: Option<Vec<u8>>, params: (String, Vec<u8>))
-> Result<(Option<Vec<u8>>, (Option<Vec<u8>>,)), String> {
let (request_id, request) = params;

// Process the request...
let response = json!({"status": "success", "data": "result"});

// Return updated state and response
Ok((Some(updated_state), (Some(response),)))
}

Handle channel open request

Called when another actor requests to open a communication channel.

Parameters

• state - The current actor state or None if not initialized
• params - Tuple containing:
• json - The initial message payload

Returns

• Ok((option<list<u8>>, (channel-accept,))) - Tuple containing:
• Updated actor state (or None to retain current state)
• Channel acceptance decision
• Err(string) - Error message if open handling fails

Example

fn handle_channel_open(state: Option<Value>, params: (Value,))
-> Result<(Option<Value>, (channel_accept,)), String> {
let (initial_message,) = params;

// Decide whether to accept the channel
let accept = channel_accept {
accept: true,
error_message: None,
};

// Return updated state and acceptance decision
Ok((Some(updated_state), (accept,)))
}

Security

The actor should validate the channel request and only accept channels from trusted sources. The acceptance mechanism provides a security checkpoint.

Handle channel message

Processes a message received on an established channel.

Parameters

• state - The current actor state or None if not initialized
• params - Tuple containing:
• channel-id - ID of the channel the message was received on
• json - The message payload

Returns

• Ok((option<list<u8>>,)) - Updated actor state (or None to retain current state)
• Err(string) - Error message if message handling fails

Example

fn handle_channel_message(state: Option<Value>, params: (channel_id, Value))
-> Result<(Option<Value>,), String> {
let (channel_id, message) = params;

// Process the channel message...
println!("Received message on channel {}: {}", channel_id, message);

// Return updated state (or None to keep current state)
Ok((Some(updated_state),))
}

Handle channel close

Called when a communication channel is closed.

Parameters

• state - The current actor state or None if not initialized
• params - Tuple containing:
• channel-id - ID of the channel that was closed

Returns

• Ok((option<list<u8>>,)) - Updated actor state (or None to retain current state)
• Err(string) - Error message if close handling fails

Example

fn handle_channel_close(state: Option<Value>, params: (channel_id,))
-> Result<(Option<Value>,), String> {
let (channel_id,) = params;

// Clean up any resources associated with the channel
println!("Channel {} closed", channel_id);

// Return updated state (or None to keep current state)
Ok((Some(updated_state),))
}

Implementation Notes

This function should perform any necessary cleanup for the closed channel, such as releasing resources or updating internal state to reflect the channel closure.

Send one-way message

Sends a message to another actor without waiting for a response.

Parameters

• actor-id - ID of the target actor
• msg - JSON message payload to send

Returns

• Ok(_) - Message was successfully sent
• Err(string) - Error message if send fails

Example

use ntwk::theater::message_server_host;
use ntwk::theater::types::actor_id;
use serde_json::json;

// Send a notification
let target = actor_id { id: "logging-service".to_string() };
let log_msg = json!({
"level": "info",
"message": "User logged in",
"timestamp": 1625097600000
});
message_server_host::send(target, log_msg)?;

Security

The runtime verifies that the sender has permission to send messages to the target actor before delivery.

Send request and await response

Sends a message to another actor and waits for a response.

Parameters

• actor-id - ID of the target actor
• msg - JSON request payload to send

Returns

• Ok(json) - The response from the target actor
• Err(string) - Error message if the request fails

Example

use ntwk::theater::message_server_host;
use ntwk::theater::types::actor_id;
use serde_json::json;

// Query a data service
let data_service = actor_id { id: "data-service".to_string() };
let query = json!({
"query": "SELECT * FROM users WHERE id = ?",
"parameters": [42]
});
let result = message_server_host::request(data_service, query)?;

Implementation Notes

This function suspends the calling actor's execution until a response is received or a timeout occurs. The runtime handles the suspension efficiently without blocking other actors.

Open communication channel

Establishes a bidirectional communication channel with another actor.

Parameters

• actor-id - ID of the target actor
• initial-msg - JSON message sent as part of channel establishment

Returns

• Ok(channel-id) - ID of the established channel
• Err(string) - Error message if channel establishment fails

Example

use ntwk::theater::message_server_host;
use ntwk::theater::types::actor_id;
use serde_json::json;

// Open a channel to a streaming service
let streaming_service = actor_id { id: "data-stream".to_string() };
let subscription = json!({
"action": "subscribe",
"topics": ["market-data", "news-feed"],
"options": {"buffer_size": 100}
});
let channel = message_server_host::open_channel(streaming_service, subscription)?;

Security

Channel establishment requires mutual consent:

1. The initiator requests the channel by calling this function
2. The target actor explicitly accepts or rejects the channel

This provides a security checkpoint to prevent unwanted channels.

Send message on channel

Sends a message through an established channel.

Parameters

• channel-id - ID of the channel to send on
• msg - JSON message payload to send

Returns

• Ok(_) - Message was successfully sent
• Err(string) - Error message if send fails

Example

use ntwk::theater::message_server_host;
use serde_json::json;

// Send a message on an established channel
let update = json!({
"type": "position-update",
"x": 10.5,
"y": 20.3,
"timestamp": 1625097600000
});
message_server_host::send_on_channel(channel_id, update)?;

Implementation Notes

Messages sent on a channel are delivered in order. If the channel is closed or invalid, this function will return an error.

Close channel

Closes an open communication channel.

Parameters

• channel-id - ID of the channel to close

Returns

• Ok(_) - Channel was successfully closed
• Err(string) - Error message if close fails

Example

use ntwk::theater::message_server_host;

// Close a channel when done with it
message_server_host::close_channel(channel_id)?;

Implementation Notes

Closing a channel is a final operation - once closed, a channel cannot be reopened. Both participants receive a notification when a channel is closed.

List outstanding requests

Retrieves a list of all pending request IDs that haven't been responded to yet.

Returns

• list<string> - List of outstanding request IDs

Example

use ntwk::theater::message_server_host;

// Get all pending requests
let pending_requests = message_server_host::list_outstanding_requests();
for request_id in pending_requests {
println!("Pending request: {}", request_id);
}

Implementation Notes

This function is useful for actors that need to track and manage asynchronous request processing. It allows actors to check for pending requests and decide which ones to process next.

Respond to a specific request

Sends a response to a previously received request identified by its ID.

Parameters

• request-id - ID of the request to respond to
• response - JSON response payload to send

Returns

• Ok(_) - Response was successfully sent
• Err(string) - Error message if response fails

Example

use ntwk::theater::message_server_host;
use serde_json::json;

// Respond to a specific request
let response = json!({
"status": "success",
"data": {
"result": 42
}
});
message_server_host::respond_to_request("req-123", response)?;

Implementation Notes

This function allows actors to implement asynchronous request handling patterns, where requests are received, processed in the background, and responded to later. If the request ID is not found, an error is returned.

Cancel a pending request

Explicitly cancels a pending request without sending a response.

Parameters

• request-id - ID of the request to cancel

Returns

• Ok(_) - Request was successfully canceled
• Err(string) - Error message if cancellation fails

Example

use ntwk::theater::message_server_host;

// Cancel a request that can't be fulfilled
message_server_host::cancel_request("req-123")?;

Implementation Notes

Canceling a request causes the requester to receive an error indicating that the request was canceled. This is useful for cleanup operations and handling error cases where a proper response cannot be generated.

Logs a message to the actor's log stream.

Purpose

This function allows actors to send log messages to the Theater logging system. Messages are tagged with the actor's ID and can be viewed through the Theater CLI or event subscription system.

Parameters

• msg - The message to log

Example

// In Rust actor code
runtime::log("Processing request with ID: 12345");

Implementation Notes

Log messages are subject to the logging level configuration specified in the actor's manifest. The Theater runtime may filter or redirect logs based on this configuration.

Retrieves the actor's event chain.

Purpose

This function provides access to the actor's complete event history as a chain of cryptographically linked events. This allows actors to inspect their state evolution and verify the integrity of their history.

Returns

• chain - The actor's event chain containing all recorded events

Example

// In Rust actor code
let chain = runtime::get_chain();

// Count events by type
let mut event_counts = std::collections::HashMap::new();
for event in chain.events {
*event_counts.entry(event.event_type.clone()).or_insert(0) += 1;
}

Security

The event chain is immutable and cryptographically verifiable, ensuring that actors cannot tamper with their event history. This provides a secure audit trail of all actor actions.

Spawn a new child actor

Creates and starts a new actor from the specified manifest file.

Parameters

• manifest - Path or content of the manifest file describing the actor
• init-bytes - Optional initial state for the actor (serialized bytes)

Returns

• Ok(string) - ID of the newly created actor
• Err(string) - Error message if spawning fails

Resume a previously stopped child actor

Restarts a previously created actor using an existing manifest but with a potentially new initial state.

Parameters

• manifest - Path or content of the manifest file describing the actor
• init-state - Optional new initial state for the actor (serialized bytes)

Returns

• Ok(string) - ID of the resumed actor
• Err(string) - Error message if resuming fails

List all child actors

Retrieves a list of all children directly managed by this actor.

Returns

• list<string> - IDs of all child actors

Stop a specific child actor

Gracefully stops a child actor identified by its ID.

Parameters

• child-id - ID of the child actor to stop

Returns

• Ok(_) - Child was successfully stopped
• Err(string) - Error message if stopping fails

Restart a specific child actor

Stops and then starts a child actor, maintaining its ID but resetting its state.

Parameters

• child-id - ID of the child actor to restart

Returns

• Ok(_) - Child was successfully restarted
• Err(string) - Error message if restarting fails

Get the latest state of a child actor

Retrieves the current serialized state of a specified child actor.

Parameters

• child-id - ID of the child actor

Returns

• Ok(option<list<u8>>) - Current state of the child (None if no state)
• Err(string) - Error message if retrieving state fails

Get event history of a child actor

Retrieves the chain of events that have occurred in a child actor, providing visibility into its execution history.

Parameters

• child-id - ID of the child actor

Returns

• Ok(list<chain-event>) - List of events in the child's chain
• Err(string) - Error message if retrieving events fails

Handle a child actor error

Processes an error from a child actor, allowing the parent to react or log the error.

Parameters

• state - Optional state of the parent actor (for context)
• params - Tuple containing the child ID and error data

Returns

• Ok(tuple<option<list<u8>>, string>) - Updated state and result message
• Err(string) - Error message if handling fails

Called for each event on the WebSocket (connections, messages, disconnections)

Purpose

This function is the core of the WebSocket interface. It's called by the Theater runtime whenever a WebSocket event occurs (new connection, incoming message, disconnection). The actor implements this function to handle the events, update its state, and respond to clients.

Parameters

• state - The current state of the actor
• params - A tuple containing the WebSocket message that triggered this call

Returns

• Ok(tuple<state, tuple<websocket-response>>) - The updated state and response to send
• Err(string) - An error message if processing fails

Example

// In Rust actor code
fn handle_message(
state: State,
params: (WebsocketMessage,)
) -> Result<(State, (WebsocketResponse,)), String> {
let message = &params.0;

// Handle a text message
if message.ty == MessageType::Text {
if let Some(text) = &message.text {
// Echo the message back to the client
let response = WebsocketResponse {
messages: vec![
WebsocketMessage {
ty: MessageType::Text,
data: None,
text: Some(format!("You said: {}", text)),
},
],
};

return Ok((state, (response,)));
}
}

// Handle a new connection
if message.ty == MessageType::Connect {
// Send a welcome message
let response = WebsocketResponse {
messages: vec![
WebsocketMessage {
ty: MessageType::Text,
data: None,
text: Some("Welcome to the WebSocket server!".to_string()),
},
],
};

return Ok((state, (response,)));
}

// Return empty response for other message types
Ok((state, (WebsocketResponse { messages: vec![] },)))
}

Security

Validate all incoming messages and don't trust client-provided data. Consider size limits for message payloads and rate limiting to prevent abuse.

Implementation Notes

The function is called once for each WebSocket event. For efficient handling of multiple connections, the actor should store connection IDs or other identifying information in its state to track individual clients.