Skip to content

rpc_client

The rpc_client directory provides a mechanism for Talon to communicate with an external application (like VS Code) using JSON files. This allows Talon to send commands to the application and receive responses, even if the application doesn't have a direct API for Talon to interact with. It is designed to be robust against multiple Talon instances trying to interact with the same application simultaneously.

Here's a breakdown of the key files and how they work together:

  • types.py: This file defines the Request dataclass, which represents a command to be sent to the external application, including the command ID, arguments, and a UUID for request-response matching. It also defines a custom exception, NoFileServerException, raised when the communication directory doesn't exist.

  • write_request.py: This file contains functions for writing a Request to a file. It handles situations where a request file already exists, likely due to another Talon instance or a previous incomplete run. If the existing file is stale (older than STALE_TIMEOUT_MS), it will be deleted and overwritten. This prevents issues with multiple processes colliding. The core function here is write_json_exclusive, which ensures that only one process can write the request at a time, by creating the file in exclusive mode.

  • read_json_with_timeout.py: This file contains a function read_json_with_timeout that reads a JSON file, waiting for the file to be completely written. It does this by looking for a trailing newline character, which is added only after the JSON is completely written. It uses an exponential backoff to check the file, up to a maximum timeout of RPC_COMMAND_TIMEOUT_SECONDS. If it doesn't see the newline before the timeout, it throws an exception. This prevents races when reading a file that is being written at the same time, while also preventing deadlocks.

  • rpc_client.py: This file defines the core action rpc_client_run_command. This is the function that Talon code will call to communicate with the external application. It constructs a Request object, writes it to a file using write_request, triggers the application to process the request, reads the response from a file using read_json_with_timeout, and returns the result. It also handles errors, warnings, and request-response UUID matching for sanity checks. The function ensures that no matter what the outcome of the interaction, both request and response files are deleted.

  • get_communication_dir_path.py: This file provides a function get_communication_dir_path to determine the location of the communication directory, which is a temporary directory based on the application name and the user ID. This helps avoid conflicts between different users or applications.

  • robust_unlink.py: This file contains the robust_unlink function, which is used to delete files. It handles cases where a file cannot be deleted on Windows because it is in use by moving it to a "graveyard" directory instead. This allows the system to function without crashing, even if files are locked by other processes.

In summary, this code provides a robust and reliable way for Talon to communicate with external applications using JSON files, handling potential conflicts and errors gracefully. The rpc_client_run_command action is the primary interface for sending commands and receiving responses. The other files handle details such as file writing, reading, and cleanup.