Implement IPC for Kallichore

.github/workflows/release.yml

@@ -114,7 +114,7 @@ jobs:
 
     do_release:
         name: Trigger a new release
-        if: ${{ needs.check_release.outputs.EXISTING_RELEASE == 'false' }}
+        if: ${{ needs.check_release.outputs.EXISTING_RELEASE == 'false' && github.ref == 'refs/heads/main' }}
         runs-on: ubuntu-latest
         needs: [check_release]
         steps:
@@ -125,7 +125,7 @@ jobs:
     build_macos:
         name: Build macOS
         runs-on: [self-hosted-staging, macos, arm64]
-        needs: [do_release, get_version]
+        needs: [get_version]
         timeout-minutes: 40
 
         env:
@@ -209,7 +209,7 @@ jobs:
         name: Build Windows
         runs-on: windows-latest
         timeout-minutes: 40
-        needs: [do_release, get_version]
+        needs: [get_version]
 
         env:
             GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
@@ -254,7 +254,7 @@ jobs:
     build_linux:
         name: "Build Linux"
         uses: ./.github/workflows/release-linux.yml
-        needs: [do_release, get_version]
+        needs: [get_version]
         secrets: inherit
         with:
             version: ${{ needs.get_version.outputs.KALLICHORE_VERSION }}

CLAUDE.md

@@ -99,4 +99,77 @@ Frontend ↔ HTTP/WebSocket ↔ Kallichore ↔ ZeroMQ ↔ Jupyter Kernels
 
 Use `RUST_LOG` environment variable for detailed debugging:
 - `RUST_LOG=trace` for maximum verbosity
-- `RUST_LOG=kallichore=debug` for library-specific logging
+- `RUST_LOG=kallichore=debug` for library-specific logging
+
+## Transport Types
+
+Kallichore supports three different transport mechanisms for client connections:
+
+### TCP (Default)
+- **Platform**: All platforms (macOS, Windows, Linux)
+- **Usage**: `--transport tcp` or omit (default)
+- **Description**: Standard TCP sockets on 127.0.0.1
+- **Best for**: General purpose, cross-platform compatibility
+
+### Unix Domain Sockets
+- **Platform**: Unix-like systems only (macOS, Linux)
+- **Usage**: `--transport socket`
+- **Description**: Unix domain sockets for inter-process communication with WebSocket protocol support
+- **Protocol**: WebSocket over Unix domain sockets (supports `ws+unix:` URLs)
+- **Best for**: High performance local communication, reduced overhead
+- **Note**: Not supported on Windows
+
+### Named Pipes
+- **Platform**: Windows only
+- **Usage**: `--transport named-pipe`
+- **Description**: Windows named pipes for inter-process communication
+- **Best for**: Windows-native IPC, integration with Windows applications
+- **Note**: Not supported on Unix systems
+
+Example usage:
+```bash
+# TCP (default)
+./target/debug/kcserver --port 8080
+
+# Unix domain socket with WebSocket protocol (macOS/Linux)
+./target/debug/kcserver --transport socket
+
+# Named pipe (Windows)
+./target/debug/kcserver --transport named-pipe
+```
+
+### WebSocket Protocol Support
+
+**Unix Domain Sockets**: Starting with this version, Unix domain socket kernel client sessions use the WebSocket protocol instead of raw JSON. This enables clients to connect using `ws+unix:` URLs and provides a consistent WebSocket interface across all transport types.
+
+**Client Connection Examples**:
+- TCP WebSocket: `ws://localhost:8080/sessions/{session_id}/channels`
+- Unix Socket WebSocket: `ws+unix:/path/to/socket:/sessions/{session_id}/channels` (conceptual - actual connection via domain socket path)
+
+## Testing
+
+### Running Tests
+
+```bash
+# Run all tests
+cargo test
+
+# Run with verbose output
+cargo test -- --nocapture
+```
+
+### Test Types
+
+- **Unit tests**: Located within `src/` files using `#[cfg(test)]` modules
+- **Integration tests**: Located in `crates/kcserver/tests/`
+  - `integration_test.rs`: General TCP and WebSocket functionality
+  - `named_pipe_test.rs`: Windows named pipe specific tests (Windows only)
+- **Platform-specific tests**: Automatically disabled on unsupported platforms
+
+### Test Environment
+
+Tests automatically:
+- Start temporary server instances
+- Create isolated temporary directories
+- Handle platform-specific transport mechanisms
+- Clean up resources after completion

README.md

@@ -50,6 +50,121 @@ To make changes to the API, edit the `kallichore.json` file and then run the `sc
 > [!IMPORTANT]
 > Because we have custom behavior attached to some of the endpoints, we have some manual edits applied to the generated code. These are generally fenced with `--- Start Kallichore ---` and `--- End Kallichore ---` comments. Be sure to reapply these edits (or just revert changes that delete them) if you regenerate the API.
 
+## Connection Methods
+
+Kallichore supports multiple transport mechanisms for client connections. The server can be configured to use TCP, Unix domain sockets, or Windows named pipes.
+
+### TCP (Default)
+
+TCP is the default transport method that works across all platforms. In TCP mode, the supervisor listens on a local TCP port and accepts RPCs over HTTP. This is suitable for remote connections and works on all operating systems.
+
+Connections to individual kernels are made with WebSockets, which are established over the HTTP connection.
+
+#### Starting the server with TCP
+
+```bash
+# Use default port (random)
+./target/debug/kcserver
+
+# Use specific port
+./target/debug/kcserver --port 8080
+
+# Create a connection file with TCP
+./target/debug/kcserver --connection-file connection.json --transport tcp
+```
+
+#### Example TCP connection file
+
+When using `--connection-file`, the server writes connection details to the specified file:
+
+```json
+{
+  "port": 54321,
+  "base_path": "http://127.0.0.1:54321",
+  "transport": "tcp",
+  "server_path": "/path/to/kcserver",
+  "server_pid": 12345,
+  "bearer_token": "your-auth-token",
+  "log_path": "/path/to/logfile.log"
+}
+```
+
+### Unix Domain Sockets (Unix/Linux/macOS)
+
+Unix domain sockets provide high-performance IPC for local connections on Unix-like systems. They offer better security than TCP, since they use filesystem permissions. However, they are not available on Windows and are not suitable for remote connections.
+
+When using domain sockets, the server listens on a specific socket file instead of a TCP port. When connecting to individual kernels, each kernel gets a dedicated Unix socket for communication.
+
+#### Starting the server with Unix sockets
+
+```bash
+# Use connection file with socket (default on Unix when using --connection-file)
+./target/debug/kcserver --connection-file connection.json
+
+# Explicitly specify socket transport
+./target/debug/kcserver --connection-file connection.json --transport socket
+
+# Use specific socket path
+./target/debug/kcserver --unix-socket /tmp/kallichore.sock
+```
+
+#### Example Unix socket connection file
+
+```json
+{
+  "socket_path": "/tmp/kallichore-12345.sock",
+  "transport": "socket",
+  "server_path": "/path/to/kcserver",
+  "server_pid": 12345,
+  "bearer_token": "your-auth-token",
+  "log_path": "/path/to/logfile.log"
+}
+```
+
+### Named Pipes (Windows)
+
+Named pipes are the Windows equivalent of Unix domain sockets, providing efficient local IPC on Windows systems. They are not available on Unix-like systems and are only used for local connections.
+
+When using named pipes, the server listens on a named pipe path instead of a TCP port or Unix socket. Each kernel session also gets its own named pipe for communication.
+
+#### Starting the server with named pipes
+
+```bash
+# Use connection file with named pipe (default on Windows when using --connection-file)
+kcserver.exe --connection-file connection.json
+
+# Explicitly specify named pipe transport
+kcserver.exe --connection-file connection.json --transport named-pipe
+```
+
+#### Example named pipe connection file
+
+```json
+{
+  "named_pipe": "\\\\.\\pipe\\kallichore-12345",
+  "transport": "named-pipe",
+  "server_path": "C:\\path\\to\\kcserver.exe",
+  "server_pid": 12345,
+  "bearer_token": "your-auth-token",
+  "log_path": "C:\\path\\to\\logfile.log"
+}
+```
+
+### Transport Selection Rules
+
+The server automatically selects the appropriate transport based on:
+
+1. **Explicit `--transport` flag**: Overrides all other settings
+2. **Connection file mode**: Defaults to `socket` on Unix, `named-pipe` on Windows, `tcp` elsewhere
+3. **Direct mode**: Uses `tcp` when no connection file is specified
+
+### Security Considerations
+
+- **TCP**: Binds to `127.0.0.1` (localhost only) by default for security
+- **Unix Sockets**: Use filesystem permissions for access control
+- **Named Pipes**: Use Windows security descriptors for access control
+- **Authentication**: All transports support bearer token authentication when enabled
+
 ## Repository Structure
 
 ```

crates/kallichore_api/README.md

@@ -14,7 +14,7 @@ To see how to make this your own, look here:
 [README]((https://openapi-generator.tech))
 
 - API version: 1.0.0
-- Build date: 2025-06-09T10:30:16.634931-07:00[America/Los_Angeles]
+- Build date: 2025-06-25T12:12:05.755509-07:00[America/Los_Angeles]
 - Generator version: 7.13.0
 
 For more information, please visit [https://posit.co](https://posit.co)
@@ -91,7 +91,7 @@ cargo run --example client GetServerConfiguration
 cargo run --example client ListSessions
 cargo run --example client ServerStatus
 cargo run --example client ShutdownServer
-cargo run --example client ChannelsWebsocket
+cargo run --example client ChannelsUpgrade
 cargo run --example client ConnectionInfo
 cargo run --example client DeleteSession
 cargo run --example client GetSession
@@ -142,7 +142,7 @@ Method | HTTP request | Description
 [**set-server-configuration**](docs/default_api.md#set-server-configuration) | **POST** /server_configuration | Change the server configuration
 [**shutdown-server**](docs/default_api.md#shutdown-server) | **POST** /shutdown | Shut down all sessions and the server itself
 [**adopt-session**](docs/default_api.md#adopt-session) | **PUT** /sessions/{session_id}/adopt | Adopt an existing session
-[**channels-websocket**](docs/default_api.md#channels-websocket) | **GET** /sessions/{session_id}/channels | Upgrade to a WebSocket for channel communication
+[**channels-upgrade**](docs/default_api.md#channels-upgrade) | **GET** /sessions/{session_id}/channels | Upgrade to a WebSocket or domain socket for channel communication
 [**connection-info**](docs/default_api.md#connection-info) | **GET** /sessions/{session_id}/connection_info | Get Jupyter connection information for the session
 [**delete-session**](docs/default_api.md#delete-session) | **DELETE** /sessions/{session_id} | Delete session
 [**get-session**](docs/default_api.md#get-session) | **GET** /sessions/{session_id} | Get session details