feat: added example code for a few languages

Author: shanefagan

.gitignore

@@ -22,3 +22,7 @@
 .DS_Store
 **/*.rs.bk
 
+# Compiled Examples
+/examples/c/get_active_game
+/examples/rust/target/
+/examples/rust/Cargo.lock

examples/README.md

@@ -0,0 +1,34 @@
+# Contextd Examples
+
+This directory contains examples of how to interact with the `contextd` daemon from different programming languages.
+
+Because `contextd` uses [Varlink](https://varlink.org) over standard Unix sockets, you can use any language that supports Unix domain sockets and JSON serialization.
+
+## Available Examples
+
+### 1. Python
+Python is a great choice for scripting against `contextd` because it has built-in support for Unix sockets and JSON, requiring zero external dependencies.
+- **`python/get_active_game.py`**: Queries the core daemon for the currently foregrounded game.
+- **`python/subscribe_rgb.py`**: Subscribes to real-time ambient lighting updates from the RGB observer socket.
+
+### 2. Shell
+For simple queries in bash scripts, the `varlinkctl` tool (usually installed alongside varlink) allows one-line interactions.
+- **`shell/get_diagnostics.sh`**: Uses `varlinkctl` to query system diagnostics.
+
+### 3. Rust
+While the `contextd` daemon itself is written in Rust and uses the `varlink` crate, you can also interact with it using nothing but the standard library and `serde_json`.
+- **`rust/src/main.rs`**: A standard Cargo project showing how to connect to the Unix socket and parse a JSON response.
+  *Run it with:* `cd rust && cargo run`
+
+### 4. C
+A minimal C example demonstrating how to use POSIX sockets to send a Varlink JSON request and read the response.
+- **`c/get_active_game.c`**: Pure C with no external dependencies (uses standard `sys/socket.h` and `sys/un.h`).
+  *Compile and run:* `gcc c/get_active_game.c -o get_active_game && ./get_active_game`
+
+## Socket Paths
+Remember the daemon exposes three interfaces:
+1. **Core Socket**: `/run/contextd/public/contextd.socket`
+2. **RGB Observer**: `/run/contextd/public/contextd-rgb-observer.socket`
+3. **RGB Control**: `/run/contextd/private/contextd-rgb-control.socket`
+
+> **Note:** The daemon must be running for these examples to work.

examples/c/get_active_game.c

@@ -0,0 +1,62 @@
+// Compile with: gcc get_active_game.c -o get_active_game
+// Run with: ./get_active_game
+
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+#include <unistd.h>
+#include <sys/socket.h>
+#include <sys/un.h>
+
+#define SOCKET_PATH "/run/contextd/public/contextd.socket"
+
+// Note: String literals in C implicitly have a null terminator ('\0') at the end.
+// We use sizeof() which includes this null terminator because Varlink requires it.
+#define REQUEST "{\"method\":\"com.performativenonsense.contextd.GetActiveGame\",\"parameters\":{}}"
+
+int main() {
+    int sock = socket(AF_UNIX, SOCK_STREAM, 0);
+    if (sock < 0) {
+        perror("socket");
+        return 1;
+    }
+
+    struct sockaddr_un addr;
+    memset(&addr, 0, sizeof(addr));
+    addr.sun_family = AF_UNIX;
+    strncpy(addr.sun_path, SOCKET_PATH, sizeof(addr.sun_path) - 1);
+
+    if (connect(sock, (struct sockaddr*)&addr, sizeof(addr)) < 0) {
+        perror("connect");
+        fprintf(stderr, "Is the contextd daemon running?\n");
+        close(sock);
+        return 1;
+    }
+
+    // Send the varlink request (including the null byte)
+    if (write(sock, REQUEST, sizeof(REQUEST)) < 0) {
+        perror("write");
+        close(sock);
+        return 1;
+    }
+
+    // Read the response until we hit the null byte
+    char buffer[4096];
+    int bytes_read;
+    printf("Raw JSON Response:\n");
+    
+    while ((bytes_read = read(sock, buffer, sizeof(buffer))) > 0) {
+        for (int i = 0; i < bytes_read; i++) {
+            if (buffer[i] == '\0') {
+                printf("\n");
+                close(sock);
+                return 0;
+            } else {
+                putchar(buffer[i]);
+            }
+        }
+    }
+
+    close(sock);
+    return 0;
+}

examples/python/get_active_game.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python3
+import socket
+import json
+import sys
+
+# Path to the public core socket
+SOCKET_PATH = "/run/contextd/public/contextd.socket"
+
+def main():
+    try:
+        # Create a Unix domain socket
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.connect(SOCKET_PATH)
+    except FileNotFoundError:
+        print(f"Error: Could not connect to {SOCKET_PATH}. Is contextd running?")
+        sys.exit(1)
+
+    # Varlink requests are JSON objects ending with a null byte
+    request = {
+        "method": "com.performativenonsense.contextd.GetActiveGame",
+        "parameters": {}
+    }
+    
+    # Send the request
+    message = json.dumps(request).encode('utf-8') + b'\0'
+    sock.sendall(message)
+
+    # Read the response (read until the null byte)
+    data = bytearray()
+    while True:
+        chunk = sock.recv(1024)
+        if not chunk:
+            break
+        data.extend(chunk)
+        if b'\0' in chunk:
+            break
+
+    # Parse and print the response
+    response_str = data.split(b'\0')[0].decode('utf-8')
+    response = json.loads(response_str)
+
+    if "error" in response:
+        print(f"Error: {response['error']}")
+    else:
+        game = response.get("parameters", {}).get("game")
+        if game:
+            print(f"Active Game Detected:")
+            print(f"  Name:   {game.get('name')}")
+            print(f"  Source: {game.get('source')}")
+            print(f"  PID:    {game.get('pid')}")
+        else:
+            print("No active game is currently foregrounded.")
+
+if __name__ == "__main__":
+    main()

examples/python/subscribe_rgb.py

@@ -0,0 +1,65 @@
+#!/usr/bin/env python3
+import socket
+import json
+import sys
+
+# Path to the public RGB observer socket
+SOCKET_PATH = "/run/contextd/public/contextd-rgb-observer.socket"
+
+def main():
+    try:
+        sock = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
+        sock.connect(SOCKET_PATH)
+    except FileNotFoundError:
+        print(f"Error: Could not connect to {SOCKET_PATH}. Is contextd running in RGB mode?")
+        sys.exit(1)
+
+    # Send a subscription request with "more": True
+    request = {
+        "method": "com.performativenonsense.contextd.rgb.Observer.SubscribeLightingContext",
+        "parameters": {},
+        "more": True
+    }
+    
+    message = json.dumps(request).encode('utf-8') + b'\0'
+    sock.sendall(message)
+
+    print("Subscribed to RGB lighting updates. Press Ctrl+C to stop.")
+
+    # Read the stream of responses
+    buffer = bytearray()
+    try:
+        while True:
+            chunk = sock.recv(4096)
+            if not chunk:
+                print("Connection closed by daemon.")
+                break
+                
+            buffer.extend(chunk)
+            
+            # Process complete messages (separated by null bytes)
+            while b'\0' in buffer:
+                msg_bytes, buffer = buffer.split(b'\0', 1)
+                
+                try:
+                    response = json.loads(msg_bytes.decode('utf-8'))
+                    if "error" in response:
+                        print(f"Error: {response['error']}")
+                        continue
+                        
+                    params = response.get("parameters", {})
+                    color = params.get("main_color")
+                    
+                    if color:
+                        print(f"New Vibe Color -> R: {color.get('r'):3} | G: {color.get('g'):3} | B: {color.get('b'):3} | A: {color.get('a'):3}")
+                    
+                except json.JSONDecodeError:
+                    pass
+
+    except KeyboardInterrupt:
+        print("\nUnsubscribing...")
+    finally:
+        sock.close()
+
+if __name__ == "__main__":
+    main()

examples/rust/Cargo.toml

@@ -0,0 +1,7 @@
+[package]
+name = "contextd-rust-example"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+serde_json = "1.0"

examples/rust/src/main.rs

@@ -0,0 +1,53 @@
+use std::io::{Read, Write};
+use std::os::unix::net::UnixStream;
+
+fn main() -> std::io::Result<()> {
+    let socket_path = "/run/contextd/public/contextd.socket";
+    
+    println!("Connecting to {}...", socket_path);
+    
+    // Connect to the Unix socket
+    let mut stream = match UnixStream::connect(socket_path) {
+        Ok(stream) => stream,
+        Err(e) => {
+            eprintln!("Failed to connect to contextd socket: {}", e);
+            eprintln!("Is the contextd daemon running?");
+            std::process::exit(1);
+        }
+    };
+    
+    // Format the varlink request (JSON object)
+    let request = serde_json::json!({
+        "method": "com.performativenonsense.contextd.GetActiveGame",
+        "parameters": {}
+    });
+    
+    // Varlink requires requests to be terminated by a null byte
+    let mut message = serde_json::to_vec(&request).unwrap();
+    message.push(b'\0');
+    
+    // Send the request
+    stream.write_all(&message)?;
+    
+    // Read the response up to the null byte
+    let mut buffer = Vec::new();
+    let mut buf = [0; 1024];
+    loop {
+        let bytes_read = stream.read(&mut buf)?;
+        if bytes_read == 0 {
+            break;
+        }
+        for &b in &buf[..bytes_read] {
+            if b == b'\0' {
+                // Parse and print the response
+                if let Ok(response) = serde_json::from_slice::<serde_json::Value>(&buffer) {
+                    println!("Response:\n{:#?}", response);
+                }
+                return Ok(());
+            }
+            buffer.push(b);
+        }
+    }
+    
+    Ok(())
+}

examples/shell/get_diagnostics.sh

@@ -0,0 +1,20 @@
+#!/bin/bash
+# This script uses the varlinkctl utility to query the contextd daemon.
+
+SOCKET="unix:/run/contextd/public/contextd.socket"
+INTERFACE="com.performativenonsense.contextd"
+
+if ! command -v varlinkctl &> /dev/null; then
+    echo "Error: varlinkctl is not installed. Please install it (usually available in the 'varlink' package)."
+    exit 1
+fi
+
+echo "Querying system diagnostics from contextd..."
+echo "------------------------------------------"
+
+# Use jq if available for pretty printing, otherwise just output the raw JSON
+if command -v jq &> /dev/null; then
+    varlinkctl call "$SOCKET/$INTERFACE.GetDiagnostics" | jq .
+else
+    varlinkctl call "$SOCKET/$INTERFACE.GetDiagnostics"
+fi