portacode 0.3.11.dev2__tar.gz → 0.3.11.dev3__tar.gz

{portacode-0.3.11.dev2 → portacode-0.3.11.dev3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: portacode
-Version: 0.3.11.dev2
+Version: 0.3.11.dev3
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian

{portacode-0.3.11.dev2 → portacode-0.3.11.dev3}/portacode/_version.py

@@ -17,5 +17,5 @@ __version__: str
 __version_tuple__: VERSION_TUPLE
 version_tuple: VERSION_TUPLE
 
-__version__ = version = '0.3.11.dev2'
-__version_tuple__ = version_tuple = (0, 3, 11, 'dev2')
+__version__ = version = '0.3.11.dev3'
+__version_tuple__ = version_tuple = (0, 3, 11, 'dev3')

portacode-0.3.11.dev3/portacode/connection/handlers/WEBSOCKET_PROTOCOL.md

@@ -0,0 +1,423 @@
+# WebSocket Communication Protocol
+
+This document outlines the WebSocket communication protocol between the Portacode server and the connected client devices.
+
+## Protocol Architecture
+
+This protocol uses a **unified message structure** throughout the entire system. No message transformations occur between layers, ensuring consistency and eliminating complexity.
+
+## Raw Message Format
+
+All communication over the WebSocket is managed by a [multiplexer](./multiplex.py) that wraps every message in a JSON object with a `device_channel` and a `payload`. This allows for multiple virtual communication channels over a single connection.
+
+**Raw Message Structure:**
+
+```json
+{
+  "device_channel": "<channel_id>",
+  "payload": {
+    // This is where the Action or Event object goes
+  }
+}
+```
+
+*   `device_channel` (string|integer, mandatory): Identifies the virtual channel on the device side. When sending control commands to the device, they should be sent to channel 0. When the device responds to such control commands or sends system events, they will also be sent on channel 0. When a terminal session is created in the device, it is assigned a UUID, and that UUID becomes the device_channel for communicating to that specific terminal.
+*   `payload` (object, mandatory): The content of the message, which will be either an [Action](#actions) or an [Event](#events) object.
+
+---
+
+## Actions
+
+Actions are messages sent from the server to the device, placed within the `payload` of a raw message. They instruct the device to perform a specific operation and are handled by the [`BaseHandler`](./base.py) and its subclasses.
+
+**Action Structure (inside the `payload`):**
+
+```json
+{
+  "command": "<command_name>",
+  "payload": {
+    "arg1": "value1",
+    "...": "..."
+  },
+  "client_channel": "<session_id>"
+}
+```
+
+*   `command` (string, mandatory): The name of the action to be executed (e.g., `terminal_start`).
+*   `payload` (object, mandatory): An object containing the specific arguments for the action.
+*   `client_channel` (string, mandatory): A session identifier that the device will echo back in its response. This identifies which client session on the server side is communicating with the device. The device uses this to track active client sessions and ensure messages are only sent to connected clients. This works like a return address - the device_channel specifies which application on the device handles the message, while the client_channel specifies which client session should receive the response.
+
+### Session Management and Event Subscriptions
+
+**Client Session Tracking**: Devices maintain awareness of active client sessions through explicit session management commands. The server notifies devices when client sessions connect, disconnect, or change their event subscriptions.
+
+**Mandatory Client Channel**: All commands sent to devices MUST include a `client_channel` to enable proper session tracking and response routing.
+
+**Event Subscription System**: Client sessions can specify which events they want to receive through subscription management. This allows devices to filter events and reduce bandwidth usage by only sending relevant updates to interested clients.
+
+---
+
+### `terminal_start`
+
+Initiates a new terminal session on the device. Handled by [`terminal_start`](./terminal_handlers.py).
+
+**Payload Fields:**
+
+*   `shell` (string, optional): The shell to use (e.g., `/bin/bash`). Defaults to the system's default shell.
+*   `cwd` (string, optional): The working directory to start the terminal in. Defaults to the user's home directory.
+*   `project_id` (string, optional): The ID of the project this terminal is associated with.
+
+**Responses:**
+
+*   On success, the device will respond with a [`terminal_started`](#terminal_started) event.
+*   On error, a generic [`error`](#error) event is sent.
+
+### `terminal_send`
+
+Sends input data to a running terminal session. Handled by [`terminal_send`](./terminal_handlers.py).
+
+**Payload Fields:**
+
+*   `terminal_id` (string, mandatory): The ID of the terminal session to send data to.
+*   `data` (string, mandatory): The data to write to the terminal's standard input.
+
+**Responses:**
+
+*   On success, the device will respond with a [`terminal_send_ack`](#terminal_send_ack) event.
+*   On error, a generic [`error`](#error) event is sent.
+
+### `terminal_stop`
+
+Terminates a running terminal session. Handled by [`terminal_stop`](./terminal_handlers.py).
+
+**Payload Fields:**
+
+*   `terminal_id` (string, mandatory): The ID of the terminal session to stop.
+
+**Responses:**
+
+*   The device immediately responds with a [`terminal_stopped`](#terminal_stopped) event to acknowledge the request.
+*   Once the terminal is successfully stopped, a [`terminal_stop_completed`](#terminal_stop_completed) event is sent.
+*   If the terminal is not found, a [`terminal_stop_completed`](#terminal_stop_completed) with a "not_found" status is sent.
+
+### `terminal_list`
+
+Requests a list of all active terminal sessions. Handled by [`terminal_list`](./terminal_handlers.py).
+
+**Payload Fields:**
+
+*   `project_id` (string, optional): If provided, filters terminals by this project ID. If "all", lists all terminals.
+
+**Responses:**
+
+*   On success, the device will respond with a [`terminal_list`](#terminal_list-event) event.
+
+### `system_info`
+
+Requests system information from the device. Handled by [`system_info`](./system_handlers.py).
+
+**Payload Fields:**
+
+This action does not require any payload fields.
+
+**Responses:**
+
+*   On success, the device will respond with a [`system_info`](#system_info-event) event.
+
+### `file_read`
+
+Reads the content of a file. Handled by [`file_read`](./file_handlers.py).
+
+**Payload Fields:**
+
+*   `path` (string, mandatory): The absolute path to the file to read.
+
+**Responses:**
+
+*   On success, the device will respond with a [`file_read_response`](#file_read_response) event.
+*   On error, a generic [`error`](#error) event is sent.
+
+### `file_write`
+
+Writes content to a file. Handled by [`file_write`](./file_handlers.py).
+
+**Payload Fields:**
+
+*   `path` (string, mandatory): The absolute path to the file to write to.
+*   `content` (string, mandatory): The content to write to the file.
+
+**Responses:**
+
+*   On success, the device will respond with a [`file_write_response`](#file_write_response) event.
+*   On error, a generic [`error`](#error) event is sent.
+
+### `directory_list`
+
+Lists the contents of a directory. Handled by [`directory_list`](./file_handlers.py).
+
+**Payload Fields:**
+
+*   `path` (string, optional): The path to the directory to list. Defaults to the current directory.
+*   `show_hidden` (boolean, optional): Whether to include hidden files in the listing. Defaults to `false`.
+
+**Responses:**
+
+*   On success, the device will respond with a [`directory_list_response`](#directory_list_response) event.
+*   On error, a generic [`error`](#error) event is sent.
+
+### `file_info`
+
+Gets information about a file or directory. Handled by [`file_info`](./file_handlers.py).
+
+**Payload Fields:**
+
+*   `path` (string, mandatory): The path to the file or directory.
+
+**Responses:**
+
+*   On success, the device will respond with a [`file_info_response`](#file_info_response) event.
+
+### `file_delete`
+
+Deletes a file or directory. Handled by [`file_delete`](./file_handlers.py).
+
+**Payload Fields:**
+
+*   `path` (string, mandatory): The path to the file or directory to delete.
+*   `recursive` (boolean, optional): If `true`, recursively deletes a directory and its contents. Defaults to `false`.
+
+**Responses:**
+
+*   On success, the device will respond with a [`file_delete_response`](#file_delete_response) event.
+*   On error, a generic [`error`](#error) event is sent.
+
+### `session_subscribe`
+
+Manages client session subscriptions and notifies the device about active sessions and their event interests. The device stores subscription filters for each active session and uses them to determine which sessions should receive each event.
+
+**Payload Fields:**
+
+*   `client_channel` (string, mandatory): The session identifier being managed.
+*   `action` (string, mandatory): The subscription action - "connect", "disconnect", or "update".
+*   `filters` (array, optional): Array of filter objects the client is interested in. Required for "connect" and "update" actions.
+
+**Filter Object Format:**
+Each filter is a flexible object that can match against any field in event payloads:
+*   **Field Matching**: Any field name with string value or "*" for wildcard
+*   **Pattern Matching**: String values support wildcards (e.g., "terminal_*")
+*   **Multiple Conditions**: All specified fields must match for filter to match
+
+**Example Filter Objects:**
+```json
+[
+  {"event": "terminal_data", "terminal_id": "uuid-123"},
+  {"event": "terminal_*", "project_id": "project-456"}, 
+  {"event": "system_info"},
+  {"event": "*", "project_id": "project-789"},
+  {"event": "file_*", "path": "/home/user/*"}
+]
+```
+
+**Processing Architecture:**
+The device maintains a subscription registry mapping each `client_channel` to its filter objects. When broadcasting events, the device evaluates each active session's filters against the event payload to determine which sessions should receive the event.
+
+**Responses:**
+
+*   On success, the device will respond with a [`session_subscribe_ack`](#session_subscribe_ack) event.
+*   On error, a generic [`error`](#error) event is sent.
+
+---
+
+## Events
+
+Events are messages sent from the device to the server, placed within the `payload` of a raw message. They are sent in response to an action or to notify the server of a state change.
+
+**Event Structure (inside the `payload`):**
+
+```json
+{
+  "event": "<event_name>",
+  // Event-specific fields...
+  "client_channels": ["<session_id1>", "<session_id2>"]
+}
+```
+
+*   `event` (string, mandatory): The name of the event being sent (e.g., `terminal_started`).
+*   <a name="client_channels"></a>`client_channels` (array, optional): List of client session identifiers that should receive this event. For direct responses to commands, this contains the single `client_channel` from the original request. For broadcast events, this contains all client sessions whose subscription filters matched the event. The server uses this to route the event to the correct client sessions.
+
+### Event Broadcasting and Session Awareness
+
+**Targeted Events**: Events that are direct responses to commands include the original `client_channel` in the `client_channels` array, ensuring they are routed only to the requesting session.
+
+**Broadcast Events**: Events that are not direct responses (such as spontaneous terminal exits or system notifications) are processed through subscription filtering. The device evaluates the event payload against each active session's filter objects to determine which sessions should receive the event.
+
+**Subscription Filtering Process**:
+1. Device generates an event with its payload fields
+2. For each active client session, device evaluates session's filter objects against event payload
+3. If any filter matches, the session's `client_channel` is added to the `client_channels` array
+4. Event is sent once with all matching `client_channels`, minimizing network traffic
+5. Server routes the single event to all specified client sessions
+
+**Filter Matching**: A filter matches an event if all specified fields in the filter have corresponding fields in the event payload with matching values (supporting wildcards like `terminal_*` or `*`).
+
+**Efficiency Benefits**:
+- **Single Event Transmission**: Each event is sent once from device to server, regardless of how many client sessions need it
+- **Flexible Filtering**: Clients can filter on any event field without protocol changes
+- **Minimal Bandwidth**: Only events with at least one interested client session are transmitted
+- **Simple Routing**: Server receives pre-filtered events with target client sessions already identified
+
+---
+
+### <a name="error"></a>`error`
+
+A generic event sent when an error occurs during the execution of an action.
+
+**Event Fields:**
+
+*   `message` (string, mandatory): A description of the error that occurred.
+
+### <a name="session_subscribe_ack"></a>`session_subscribe_ack`
+
+Acknowledges the receipt and processing of a `session_subscribe` action. This confirms that the device has updated its session registry and subscription filters.
+
+**Event Fields:**
+
+*   `action` (string, mandatory): The subscription action that was processed ("connect", "disconnect", or "update").
+*   `active_sessions` (integer, mandatory): The total number of currently active client sessions.
+*   `filter_count` (integer, mandatory): The number of filter objects registered for the managed session (0 for disconnect action).
+
+### <a name="terminal_started"></a>`terminal_started`
+
+Confirms that a new terminal session has been successfully started. Triggered by a `terminal_start` action. Handled by [`terminal_start`](./terminal_handlers.py).
+
+**Event Fields:**
+
+*   `terminal_id` (string, mandatory): The unique ID of the newly created terminal session.
+*   `device_channel` (string, mandatory): The device channel name for terminal I/O (same as terminal_id).
+*   `project_id` (string, optional): The project ID associated with the terminal.
+
+### <a name="terminal_exit"></a>`terminal_exit`
+
+Notifies the server that a terminal session has terminated. This can be due to the process ending or the session being stopped. Handled by [`terminal_start`](./terminal_handlers.py).
+
+**Event Fields:**
+
+*   `terminal_id` (string, mandatory): The ID of the terminal session that has exited.
+*   `returncode` (integer, mandatory): The exit code of the terminal process.
+*   `project_id` (string, optional): The project ID associated with the terminal.
+
+### <a name="terminal_send_ack"></a>`terminal_send_ack`
+
+Acknowledges the receipt of a `terminal_send` action. Handled by [`terminal_send`](./terminal_handlers.py). This event carries no extra fields.
+
+### <a name="terminal_stopped"></a>`terminal_stopped`
+
+Acknowledges that a `terminal_stop` request has been received and is being processed. Handled by [`terminal_stop`](./terminal_handlers.py).
+
+**Event Fields:**
+
+*   `terminal_id` (string, mandatory): The ID of the terminal being stopped.
+*   `status` (string, mandatory): The status of the stop operation (e.g., "stopping", "not_found").
+*   `message` (string, mandatory): A descriptive message about the status.
+*   `project_id` (string, optional): The project ID associated with the terminal.
+
+### <a name="terminal_stop_completed"></a>`terminal_stop_completed`
+
+Confirms that a terminal session has been successfully stopped. Handled by [`terminal_stop`](./terminal_handlers.py).
+
+**Event Fields:**
+
+*   `terminal_id` (string, mandatory): The ID of the stopped terminal.
+*   `status` (string, mandatory): The final status ("success", "timeout", "error", "not_found").
+*   `message` (string, mandatory): A descriptive message.
+*   `project_id` (string, optional): The project ID associated with the terminal.
+
+### <a name="terminal_list-event"></a>`terminal_list`
+
+Provides the list of active terminal sessions in response to a `terminal_list` action. Handled by [`terminal_list`](./terminal_handlers.py).
+
+**Event Fields:**
+
+*   `sessions` (array, mandatory): A list of active terminal session objects.
+*   `project_id` (string, optional): The project ID that was used to filter the list.
+
+### <a name="system_info-event"></a>`system_info`
+
+Provides system information in response to a `system_info` action. Handled by [`system_info`](./system_handlers.py).
+
+**Event Fields:**
+
+*   `info` (object, mandatory): An object containing system information, including:
+    *   `cpu_percent` (float): CPU usage percentage.
+    *   `memory` (object): Memory usage statistics.
+    *   `disk` (object): Disk usage statistics.
+    *   `os_info` (object): Operating system details, including `os_type`, `os_version`, `architecture`, `default_shell`, and `default_cwd`.
+
+### <a name="file_read_response"></a>`file_read_response`
+
+Returns the content of a file in response to a `file_read` action. Handled by [`file_read`](./file_handlers.py).
+
+**Event Fields:**
+
+*   `path` (string, mandatory): The path of the file that was read.
+*   `content` (string, mandatory): The content of the file.
+*   `size` (integer, mandatory): The size of the file in bytes.
+
+### <a name="file_write_response"></a>`file_write_response`
+
+Confirms that a file has been written successfully in response to a `file_write` action. Handled by [`file_write`](./file_handlers.py).
+
+**Event Fields:**
+
+*   `path` (string, mandatory): The path of the file that was written.
+*   `bytes_written` (integer, mandatory): The number of bytes written to the file.
+*   `success` (boolean, mandatory): Indicates whether the write operation was successful.
+
+### <a name="directory_list_response"></a>`directory_list_response`
+
+Returns the contents of a directory in response to a `directory_list` action. Handled by [`directory_list`](./file_handlers.py).
+
+**Event Fields:**
+
+*   `path` (string, mandatory): The path of the directory that was listed.
+*   `items` (array, mandatory): A list of objects, each representing a file or directory in the listed directory.
+*   `count` (integer, mandatory): The number of items in the `items` list.
+
+### <a name="file_info_response"></a>`file_info_response`
+
+Returns information about a file or directory in response to a `file_info` action. Handled by [`file_info`](./file_handlers.py).
+
+**Event Fields:**
+
+*   `path` (string, mandatory): The path of the file or directory.
+*   `exists` (boolean, mandatory): Indicates whether the file or directory exists.
+*   `is_file` (boolean, optional): Indicates if the path is a file.
+*   `is_dir` (boolean, optional): Indicates if the path is a directory.
+*   `is_symlink` (boolean, optional): Indicates if the path is a symbolic link.
+*   `size` (integer, optional): The size of the file in bytes.
+*   `modified` (float, optional): The last modification time (timestamp).
+*   `accessed` (float, optional): The last access time (timestamp).
+*   `created` (float, optional): The creation time (timestamp).
+*   `permissions` (string, optional): The file permissions in octal format.
+*   `owner_uid` (integer, optional): The user ID of the owner.
+*   `group_gid` (integer, optional): The group ID of the owner.
+
+### <a name="file_delete_response"></a>`file_delete_response`
+
+Confirms that a file or directory has been deleted in response to a `file_delete` action. Handled by [`file_delete`](./file_handlers.py).
+
+**Event Fields:**
+
+*   `path` (string, mandatory): The path of the deleted file or directory.
+*   `deleted_type` (string, mandatory): The type of the deleted item ("file" or "directory").
+*   `success` (boolean, mandatory): Indicates whether the deletion was successful.
+
+---
+
+## Future Enhancements
+
+### Bandwidth Management
+The protocol will support configurable rate limiting and bandwidth monitoring to prevent resource exhaustion and ensure fair usage across multiple client sessions. This will include per-session bandwidth quotas, throttling mechanisms, and automatic rate limiting enforcement.
+
+### Channel Traffic Isolation
+Different device channels (control, terminal sessions, file operations) will have separate traffic shaping to ensure high-priority control commands are not delayed by high-volume terminal output. This includes priority queuing and per-channel bandwidth allocation.

{portacode-0.3.11.dev2 → portacode-0.3.11.dev3}/portacode/connection/handlers/base.py

@@ -40,15 +40,58 @@ class BaseHandler(ABC):
         """
         pass
     
+    def _normalize_field_names(self, message: Dict[str, Any]) -> Dict[str, Any]:
+        """Normalize field names for backward compatibility.
+        
+        Supports both old and new field names:
+        - 'cmd' -> 'command' 
+        - 'reply_channel' -> 'client_channel'
+        
+        Args:
+            message: Original message dict
+            
+        Returns:
+            Message dict with normalized field names
+        """
+        normalized = message.copy()
+        
+        # Support both 'cmd' and 'command' fields
+        if 'cmd' in normalized and 'command' not in normalized:
+            normalized['command'] = normalized['cmd']
+            logger.debug("Converted 'cmd' to 'command' for backward compatibility")
+        
+        # Support both 'reply_channel' and 'client_channel' fields  
+        if 'reply_channel' in normalized and 'client_channel' not in normalized:
+            normalized['client_channel'] = normalized['reply_channel']
+            logger.debug("Converted 'reply_channel' to 'client_channel' for backward compatibility")
+            
+        return normalized
+    
+    def _get_client_channels(self, client_channel: Optional[str] = None) -> Optional[list]:
+        """Convert single client_channel to client_channels array for responses.
+        
+        Args:
+            client_channel: Single client channel identifier
+            
+        Returns:
+            List with single client channel, or None if no channel provided
+        """
+        if client_channel:
+            return [client_channel]
+        return None
+
     async def send_response(self, payload: Dict[str, Any], reply_channel: Optional[str] = None) -> None:
         """Send a response back to the gateway.
         
         Args:
             payload: Response payload
-            reply_channel: Optional reply channel
+            reply_channel: Optional reply channel (supports both old and new names)
         """
+        # Support both reply_channel (old) and client_channel (new) parameter names
         if reply_channel:
-            payload["reply_channel"] = reply_channel
+            # Add both formats for backward compatibility during transition
+            payload["reply_channel"] = reply_channel  # Old format
+            payload["client_channels"] = [reply_channel]  # New format
         await self.control_channel.send(payload)
     
     async def send_error(self, message: str, reply_channel: Optional[str] = None) -> None:
@@ -56,11 +99,13 @@ class BaseHandler(ABC):
         
         Args:
             message: Error message
-            reply_channel: Optional reply channel
+            reply_channel: Optional reply channel (supports both old and new names)
         """
         payload = {"event": "error", "message": message}
         if reply_channel:
-            payload["reply_channel"] = reply_channel
+            # Add both formats for backward compatibility during transition
+            payload["reply_channel"] = reply_channel  # Old format
+            payload["client_channels"] = [reply_channel]  # New format
         await self.control_channel.send(payload)
 
 
@@ -81,11 +126,14 @@ class AsyncHandler(BaseHandler):
     
     async def handle(self, message: Dict[str, Any], reply_channel: Optional[str] = None) -> None:
         """Handle the command by executing it and sending the response."""
+        # Normalize field names for backward compatibility
+        normalized_message = self._normalize_field_names(message)
+        
         logger.info("handler: Processing command %s with reply_channel=%s", 
                    self.command_name, reply_channel)
         
         try:
-            response = await self.execute(message)
+            response = await self.execute(normalized_message)
             logger.info("handler: Command %s executed successfully", self.command_name)
             await self.send_response(response, reply_channel)
         except Exception as exc:
@@ -110,9 +158,12 @@ class SyncHandler(BaseHandler):
     
     async def handle(self, message: Dict[str, Any], reply_channel: Optional[str] = None) -> None:
         """Handle the command by executing it in an executor and sending the response."""
+        # Normalize field names for backward compatibility
+        normalized_message = self._normalize_field_names(message)
+        
         try:
             loop = asyncio.get_running_loop()
-            response = await loop.run_in_executor(None, self.execute, message)
+            response = await loop.run_in_executor(None, self.execute, normalized_message)
             await self.send_response(response, reply_channel)
         except Exception as exc:
             logger.exception("Error in sync handler %s: %s", self.command_name, exc)

{portacode-0.3.11.dev2 → portacode-0.3.11.dev3}/portacode.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: portacode
-Version: 0.3.11.dev2
+Version: 0.3.11.dev3
 Summary: Portacode CLI client and SDK
 Home-page: https://github.com/portacode/portacode
 Author: Meena Erian

{portacode-0.3.11.dev2 → portacode-0.3.11.dev3}/portacode.egg-info/SOURCES.txt

@@ -27,6 +27,7 @@ portacode/connection/client.py
 portacode/connection/multiplex.py
 portacode/connection/terminal.py
 portacode/connection/handlers/README.md
+portacode/connection/handlers/WEBSOCKET_PROTOCOL.md
 portacode/connection/handlers/__init__.py
 portacode/connection/handlers/base.py
 portacode/connection/handlers/file_handlers.py