rotnetz Host API Documentation

This document describes the host API for creating network hosts that can receive and respond to remote procedure calls. For a detailed explanation of how requests are processed and the overall message flow, see the Networking Architecture document.

Request Processing

Request Lifecycle

When a host receives a request, the following sequence occurs:

1. Receiver Thread receives the request message on the main protocol
2. Acknowledgment is sent back via the direct protocol (for synchronous requests)
3. Message is placed in the shared queue
4. Handler Thread picks up the message from the queue
5. Method Lookup - the requested method is found in the registered methods
6. Execution - the method is executed with provided parameters using pcall
7. Response is constructed with the result or error
8. Response is sent back to the client via the receive protocol

Threading Model

Hosts use a multi-threaded architecture for better performance:

• Receiver Thread(s): Listens on the main protocol and receives incoming requests

  • Puts messages into a shared queue
  • Sends "ack" for synchronous requests

• Handler Thread(s): Processes messages from the queue

  • Looks up and executes the requested method
  • Constructs and sends responses

This separation allows the host to continue receiving requests even while processing previous ones.

Error Handling

Hosts automatically handle errors during method execution:

Best Practices

Method Design

1. Keep methods fast - handler threads are blocking during method execution
2. Handle your own errors - use try/catch or pcall to prevent crashes
3. Validate inputs - check parameter types and values
4. Provide good descriptions - document what each method does
5. Return meaningful errors - include helpful error messages

Threading Considerations

1. Use appropriate thread count - more threads for high load, fewer for simple cases
2. Avoid long-running operations - they block handler threads
3. Consider CPU usage - complex calculations may degrade performance
4. Use async patterns - if methods need to wait, consider async approaches

Performance Tips

1. Monitor queue size - growing queues indicate bottlenecks
2. Profile methods - identify slow methods that need optimization
3. Batch operations - combine multiple operations when possible
4. Use caching - cache frequent results to reduce computation

Constructor

Host(protocol, networkMask, logger)

Creates a new host instance.

Parameters:

• protocol (string): Base protocol name
• networkMask (string, optional): Prefix for protocol names. Defaults to empty string
• logger (table, optional): Logger instance. Defaults to default logger from lumberjack

Returns:

• host (table): Host instance with the following methods and properties

Properties:

• protocol (string): Full protocol name with network mask
• networkMask (string): Network mask used
• directProtocol (string): Protocol for direct communication
• methods (table): Table of registered methods

Methods

getMethods()

Returns a table of available methods with descriptions.

Returns:

• methods (table): Key-value pairs where keys are method names and values are descriptions

addMethod(name, method, description)

Adds a method to the host.

Parameters:

• name (string): Name of the method
• method (function): Function to execute when method is called
• description (string, optional): Description of the method. Defaults to "the developer implementing this method deemed his work not worth describing"

start(n)

Starts the host with multiple handler threads.

Parameters:

• n (number, optional): Number of handler threads. Defaults to 4

Note: This method runs indefinitely and will block the current thread.

startSingle()

Starts the host with a single handler thread.

Note: This method runs indefinitely and will block the current thread.

Internal Methods

_handle(senderId, message)

Handles an incoming message by executing the requested method.

Parameters:

• senderId (number): ID of the sender
• message (table): Message containing methodName and parameters

_sendResponseMessage(senderId, message, protocol)

Sends a response message to the client.

Parameters:

• senderId (number): ID of the recipient
• message (table): Message to send
• protocol (string, optional): Protocol to use

_massHandler(queue)

Mass handler that processes messages from the queue.

Parameters:

• queue (ParellelQueue): ParallelQueue instance for message processing

_messageReceive()

Receives messages from the network.

Returns:

• senderId (number): ID of the sender
• message (table): Received message

_massReceive(queue)

Mass receiver that puts messages into the queue.

Parameters:

• queue (ParallelQueue): ParallelQueue instance for storing messages

_massReceiveSingle()

Single thread receiver that handles messages immediately.

Built-in Methods

The host automatically registers the following methods:

ping

Returns true. Used for host discovery.

listMethods

Returns a table of available methods with their descriptions.

shellRun(params)

Executes shell commands. Parameters should be a table with command arguments.

Parameters:

• params (table): Command arguments

Usage