rotnetz Networking Architecture

This document provides an overview of the rotnetz networking architecture, explaining how remote procedure calls (RPC) work and how responses are delivered.

Overview

rotnetz is a Lua library for ComputerCraft that enables remote procedure calls between computers over the rednet network. It provides a client-server architecture where:

• Hosts expose methods that can be called remotely
• Clients make requests to hosts and receive responses

Protocol Structure

rotnetz uses multiple protocols to manage the request-response cycle:

Main Protocol

• Format: {networkMask}{protocol}
• Purpose: Used by clients to send requests to hosts
• Example: If networkMask is "myNetwork" and protocol is "myProtocol", the full protocol name is "myNetworkmyProtocol"

Direct Protocol

• Format: {networkMask}direct
• Purpose: Used for acknowledgments and direct synchronous responses
• Example: "myNetworkdirect"

Receive Protocols

• Synchronous: {networkMask}callReceive
• Asynchronous: {networkMask}callReceiveAsync
• Purpose: Used by hosts to send responses back to clients
• Example: "myNetworkcallReceive"

Message Flow

Synchronous RPC

1. Client sends request:

   • Client sends a message to the host via the main protocol
   • Message contains: methodName, parameters, and the receive protocol for the response

2. Host acknowledges:

   • Host immediately sends "ack" back to the client via the direct protocol
   • This confirms the request was received

3. Client waits for response:

   • Client blocks and listens on the receive protocol (synchronous mode)

4. Host processes request:

   • Host looks up the requested method
   • Executes the method with provided parameters
   • Catches any errors using pcall

5. Host sends response:

   • Host sends response message via the receive protocol specified in the original request
   • Response contains: state (true/false), result (data or error message)

6. Client receives response:

   • Client unblocks and receives the response message
   • Returns the state and result to the caller

Asynchronous RPC

1. Client sends request:

   • Client sends a message with async = true flag
   • Client does not wait for acknowledgment

2. Host processes request:

   • Host executes the method asynchronously
   • Host sends response to the async receive protocol

3. Client receives response later:

   • Client must set up a receiver thread that listens on the async receive protocol
   • Responses are placed in a queue
   • Client polls the queue to get responses when ready

Threading Model

Host Architecture

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

• Separation of concerns: Receiving and processing happen in parallel for better throughput

Client Architecture

Clients can operate in two modes:

• Synchronous: Blocks while waiting for response
• Asynchronous: Sets up a receiver thread to handle responses in the background

Response Handling

Response Message Structure

All responses from hosts contain:

Synchronous Response Flow

Asynchronous Response Flow

Best Practices

For Clients

1. Use synchronous calls when you need immediate results and can afford to block
2. Use asynchronous calls when you need to make multiple requests or continue processing while waiting
3. Always handle errors - check the state field of responses
4. For async operations, set up a receiver thread before making async calls

For Hosts

1. Keep methods fast - handler threads are blocking during method execution
2. Handle errors gracefully - use try/catch or pcall to prevent crashes
3. Provide good descriptions when registering methods
4. Consider threading - if methods are CPU-intensive, the host's performance may degrade

Example Workflow

Synchronous Call

Asynchronous Call

Common Pitfalls

1. Missing receiver thread: Forgetting to set up a receiver thread for async operations
2. Wrong protocol: Using the wrong protocol for responses
3. Timeout issues: Not setting appropriate timeouts for synchronous calls
4. Blocking calls: Making synchronous calls in handler threads can cause deadlocks
5. Error handling: Not checking the state field of responses

See Also

• Client API Documentation - Detailed client API reference
• Host API Documentation - Detailed host API reference