guac-bridge 0.2.0__py3-none-any.whl

guac_bridge/__init__.py

@@ -0,0 +1,2 @@
+__version__ = "0.2.0"
+

guac_bridge/client.py

@@ -0,0 +1,561 @@
+#!/usr/bin/env python3
+"""Local OpenAI HTTP endpoint over an authenticated Apache Guacamole terminal."""
+import argparse
+import asyncio
+import base64
+import contextlib
+import getpass
+import json
+import logging
+import os
+import shlex
+import ssl
+import sys
+import time
+import urllib.parse
+import uuid
+
+import aiohttp
+from aiohttp import web
+
+LOG = logging.getLogger('guac-llm')
+PATHS = {'/v1/models': 'GET', '/v1/chat/completions': 'POST', '/v1/completions': 'POST'}
+
+
+class BridgeError(Exception):
+    pass
+
+
+def instruction(*args):
+    return ','.join(str(len(str(arg))) + '.' + str(arg) for arg in args) + ';'
+
+
+class Parser:
+    """Incremental Guacamole length-prefixed instruction parser."""
+    def __init__(self):
+        self.buffer = ''
+
+    def feed(self, text):
+        self.buffer += text
+        if len(self.buffer) > 16 * 1024 * 1024:
+            raise BridgeError('Guacamole instruction exceeds size limit')
+        result = []
+        start = 0
+        while start < len(self.buffer):
+            pos, args = start, []
+            while True:
+                dot = self.buffer.find('.', pos)
+                if dot < 0:
+                    self.buffer = self.buffer[start:]
+                    return result
+                length = self.buffer[pos:dot]
+                if not length.isdecimal() or len(length) > 9:
+                    raise BridgeError('Invalid Guacamole instruction length')
+                end = dot + 1 + int(length)
+                if end >= len(self.buffer):
+                    self.buffer = self.buffer[start:]
+                    return result
+                args.append(self.buffer[dot + 1:end])
+                separator = self.buffer[end]
+                pos = end + 1
+                if separator == ';':
+                    result.append(args)
+                    start = pos
+                    break
+                if separator != ',':
+                    raise BridgeError('Invalid Guacamole separator')
+        self.buffer = self.buffer[start:]
+        return result
+
+
+def parse_url(url, connection=None, data_source=None):
+    parts = urllib.parse.urlsplit(url)
+    if parts.scheme not in ('http', 'https') or not parts.netloc or parts.username or parts.password:
+        raise BridgeError('Supply an http(s) Guacamole URL without embedded credentials')
+    kind = 'c'
+    if '/client/' in parts.fragment:
+        encoded = urllib.parse.unquote(parts.fragment.split('/client/', 1)[1].split('?')[0])
+        try:
+            decoded = base64.b64decode(encoded + '=' * (-len(encoded) % 4)).decode()
+            found_id, kind, found_source = decoded.split('\0')
+        except (ValueError, UnicodeError) as exc:
+            raise BridgeError('Cannot decode connection from URL; use --connection-id and --data-source') from exc
+        connection = connection or found_id
+        data_source = data_source or found_source
+    if not connection or not data_source or kind not in ('c', 'g'):
+        raise BridgeError('Include #/client/... in URL, or supply --connection-id and --data-source')
+    base = urllib.parse.urlunsplit((parts.scheme, parts.netloc, parts.path.rstrip('/') + '/', '', ''))
+    return base, connection, kind, data_source
+
+
+def bootstrap(args):
+    executable = ('"$HOME"/' + shlex.quote(args.server_command[2:])
+                  if args.server_command.startswith('~/') else shlex.quote(args.server_command))
+    command = executable + ' ' + ' '.join(shlex.quote(str(value)) for value in (
+        '--upstream', args.upstream,
+        '--request-timeout', args.request_timeout, '--max-requests', args.max_requests)) + '\n'
+    if len(command.encode()) > 3900:
+        raise BridgeError('Remote bootstrap exceeds terminal canonical line limit')
+    return command.encode()
+
+
+class Tunnel:
+    def __init__(self, session, base, params, mode):
+        self.session, self.base, self.params, self.mode = session, base, params, mode
+        self.ws = None
+        self.ident = None
+        self.lock = asyncio.Lock()
+        self.closed = False
+
+    async def connect(self):
+        if self.mode != 'http':
+            url = self.base.replace('https://', 'wss://', 1).replace('http://', 'ws://', 1)
+            try:
+                self.ws = await self.session.ws_connect(
+                    url + 'websocket-tunnel', params=self.params, protocols=('guacamole',),
+                    heartbeat=20, max_msg_size=16 * 1024 * 1024,
+                    origin=urllib.parse.urlunsplit((*urllib.parse.urlsplit(self.base)[:2], '', '', '')))
+                self.mode = 'websocket'
+                return
+            except (aiohttp.ClientError, asyncio.TimeoutError) as exc:
+                if self.mode == 'websocket':
+                    raise BridgeError('WebSocket tunnel failed; try --transport http') from exc
+                LOG.info('WebSocket unavailable; trying Guacamole HTTP tunnel')
+        self.mode = 'http'
+        async with self.session.post(self.base + 'tunnel?connect', data=self.params,
+                                     allow_redirects=False) as response:
+            if response.status != 200:
+                raise BridgeError('HTTP tunnel connect returned status ' + str(response.status))
+            self.ident = (await response.text()).strip()
+        try:
+            uuid.UUID(self.ident)
+        except ValueError as exc:
+            raise BridgeError('HTTP tunnel did not return a tunnel UUID') from exc
+
+    async def send(self, *args):
+        payload = instruction(*args)
+        async with self.lock:
+            if self.closed:
+                raise BridgeError('Guacamole tunnel is closed')
+            if self.ws:
+                await self.ws.send_str(payload)
+            else:
+                async with self.session.post(self.base + 'tunnel?write:' + self.ident,
+                                             data=payload.encode(),
+                                             headers={'Content-Type': 'application/octet-stream'},
+                                             allow_redirects=False) as response:
+                    if response.status != 200:
+                        raise BridgeError('HTTP tunnel write failed: ' + str(response.status))
+                    await response.read()
+
+    async def messages(self):
+        if self.ws:
+            async for message in self.ws:
+                if message.type == aiohttp.WSMsgType.TEXT:
+                    yield message.data
+                elif message.type == aiohttp.WSMsgType.ERROR:
+                    raise BridgeError('WebSocket tunnel failed')
+            return
+        counter = 0
+        import codecs
+        decoder = codecs.getincrementaldecoder('utf-8')()
+        while not self.closed:
+            async with self.session.get(self.base + 'tunnel?read:' + self.ident + ':' + str(counter),
+                                        allow_redirects=False) as response:
+                if response.status != 200:
+                    raise BridgeError('HTTP tunnel read failed: ' + str(response.status))
+                async for chunk in response.content.iter_any():
+                    yield decoder.decode(chunk)
+            counter += 1
+
+    async def close(self):
+        self.closed = True
+        if self.ws:
+            await self.ws.close()
+
+
+class Bridge:
+    helper_name = 'guac-llm-server'
+
+    def helper_command(self):
+        return bootstrap(self.args)
+
+    def __init__(self, args, session, base, conn, kind, data_source, token):
+        self.args, self.session = args, session
+        self.base, self.conn, self.kind, self.data_source = base, conn, kind, data_source
+        self.token = token
+        self.tunnel = None
+        self.reader = None
+        self.maintainer = None
+        self.synced = asyncio.Event()
+        self.ready = asyncio.Event()
+        self.failed = asyncio.Event()
+        self.failure = None
+        self.input_lock = asyncio.Lock()
+        self.acks = asyncio.Queue()
+        self.input_stream = 0
+        self.output_stream = None
+        self.output_buffer = b''
+        self.requests = {}
+        self.last_seen = time.monotonic()
+        self.closing = False
+
+    async def start(self):
+        params = [('token', self.token), ('GUAC_DATA_SOURCE', self.data_source),
+                  ('GUAC_ID', self.conn), ('GUAC_TYPE', self.kind),
+                  ('GUAC_WIDTH', '1024'), ('GUAC_HEIGHT', '768'), ('GUAC_DPI', '96'),
+                  ('GUAC_TIMEZONE', 'Europe/Berlin'), ('GUAC_IMAGE', 'image/png')]
+        self.tunnel = Tunnel(self.session, self.base, params, self.args.transport)
+        await self.tunnel.connect()
+        LOG.info('Connected via %s; waiting for terminal', self.tunnel.mode)
+        self.reader = asyncio.create_task(self.read_loop())
+        await self.wait_for(self.synced.wait(), self.args.connect_timeout)
+        await self.wait_for(asyncio.sleep(self.args.startup_delay), self.args.connect_timeout)
+        ack = self.new_ack()
+        await self.tunnel.send('pipe', self.input_stream, 'text/plain', 'STDIN')
+        await self.wait_for(ack, self.args.connect_timeout)
+        await self.send_input(self.helper_command())
+        try:
+            await self.wait_for(self.ready.wait(), self.args.connect_timeout)
+        except asyncio.TimeoutError as exc:
+            raise BridgeError('Remote helper did not become ready. Check ' + self.helper_name +
+                              ' installation/PATH, shell readiness, and Guacamole STDIN/output pipes; '
+                              'try --startup-delay 5.') from exc
+        self.maintainer = asyncio.create_task(self.maintain())
+        LOG.info('Remote helper ready')
+
+    async def wait_for(self, awaitable, timeout):
+        operation = asyncio.ensure_future(awaitable)
+        failed = asyncio.create_task(self.failed.wait())
+        try:
+            done, _ = await asyncio.wait((operation, failed), timeout=timeout,
+                                         return_when=asyncio.FIRST_COMPLETED)
+            if failed in done:
+                raise BridgeError(self.failure or 'Guacamole disconnected')
+            if operation in done:
+                return operation.result()
+            raise asyncio.TimeoutError()
+        finally:
+            for task in (operation, failed):
+                if not task.done():
+                    task.cancel()
+            await asyncio.gather(operation, failed, return_exceptions=True)
+
+    def new_ack(self):
+        future = asyncio.get_running_loop().create_future()
+        self.acks.put_nowait(future)
+        return future
+
+    async def send_input(self, data):
+        async with self.input_lock:
+            pending = []
+            try:
+                for offset in range(0, len(data), 3072):
+                    pending.append(self.new_ack())
+                    await self.tunnel.send('blob', self.input_stream,
+                                           base64.b64encode(data[offset:offset + 3072]).decode())
+                    if len(pending) >= 8:
+                        await self.wait_for(pending.pop(0), self.args.connect_timeout)
+                for future in pending:
+                    await self.wait_for(future, self.args.connect_timeout)
+            except BaseException:
+                self.fail('Terminal input failed; restart the bridge')
+                raise
+
+    async def send_event(self, event):
+        await self.send_input(base64.b64encode(json.dumps(event, separators=(',', ':')).encode()) + b'\n')
+
+    def fail(self, message):
+        if self.failed.is_set() or self.closing:
+            return
+        self.failure = message
+        self.failed.set()
+        LOG.error('%s', message)
+        for queue in self.requests.values():
+            # A bounded queue can be full when the consumer is slow. Discard buffered
+            # bytes on failure; never replace a truncated stream with a success marker.
+            while not queue.empty():
+                queue.get_nowait()
+            queue.put_nowait({'type': 'error', 'message': message})
+
+    async def read_loop(self):
+        parser = Parser()
+        try:
+            async for text in self.tunnel.messages():
+                for args in parser.feed(text):
+                    opcode, *values = args
+                    if opcode == 'sync':
+                        await self.tunnel.send('sync', values[0])
+                        self.synced.set()
+                    elif opcode == 'ack' and int(values[0]) == self.input_stream:
+                        if not self.acks.empty():
+                            future = self.acks.get_nowait()
+                            if not future.done():
+                                if int(values[2]) == 0:
+                                    future.set_result(None)
+                                else:
+                                    future.set_exception(BridgeError('Guacamole rejected STDIN pipe: ' + values[2]))
+                    elif opcode == 'pipe':
+                        if values[2] == 'LLM' and self.output_stream is None:
+                            self.output_stream = int(values[0])
+                            await self.tunnel.send('ack', values[0], 'OK', 0)
+                        else:
+                            await self.tunnel.send('ack', values[0], 'Unsupported stream', 256)
+                    elif opcode == 'blob' and int(values[0]) == self.output_stream:
+                        self.output_buffer += base64.b64decode(values[1], validate=True)
+                        if len(self.output_buffer) > 128 * 1024:
+                            raise BridgeError('Remote frame exceeds limit')
+                        while b'\n' in self.output_buffer:
+                            line, self.output_buffer = self.output_buffer.split(b'\n', 1)
+                            if line.strip():
+                                event = json.loads(base64.b64decode(line.strip(), validate=True))
+                                self.dispatch(event)
+                        await self.tunnel.send('ack', values[0], 'OK', 0)
+                    elif opcode == 'end' and int(values[0]) == self.output_stream:
+                        raise BridgeError('Remote helper output pipe closed')
+                    elif opcode == 'error':
+                        raise BridgeError('Guacamole error status ' + (values[1] if len(values) > 1 else 'unknown'))
+                    elif opcode == 'disconnect':
+                        raise BridgeError('Guacamole disconnected')
+                    elif opcode in ('img', 'file', 'audio', 'video', 'body') and values:
+                        # We intentionally do not render the graphical terminal.
+                        await self.tunnel.send('ack', values[0], 'Not needed', 256)
+            self.fail('Guacamole tunnel closed; restart the bridge')
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            self.fail(str(exc) if isinstance(exc, BridgeError) else 'Guacamole transport/protocol failure: ' + type(exc).__name__)
+
+    def dispatch(self, event):
+        self.last_seen = time.monotonic()
+        if event['type'] == 'ready':
+            if event.get('version') != 1:
+                raise BridgeError('Unsupported remote helper version')
+            self.ready.set()
+        elif event['type'] != 'heartbeat':
+            queue = self.requests.get(event.get('id'))
+            if queue:
+                try:
+                    queue.put_nowait(event)
+                except asyncio.QueueFull as exc:
+                    raise BridgeError('Remote response exceeded flow control window') from exc
+
+    async def maintain(self):
+        refreshed = time.monotonic()
+        try:
+            while True:
+                await asyncio.sleep(10)
+                if time.monotonic() - self.last_seen > 45:
+                    self.fail('Remote helper heartbeat lost; restart the bridge')
+                    return
+                if time.monotonic() - refreshed > 60 and self.kind == 'c':
+                    path = 'api/session/data/' + urllib.parse.quote(self.data_source, safe='')
+                    path += '/connections/' + urllib.parse.quote(self.conn, safe='')
+                    async with self.session.get(self.base + path, params={'token': self.token},
+                                                timeout=aiohttp.ClientTimeout(total=15),
+                                                allow_redirects=False) as response:
+                        if response.status != 200:
+                            self.fail('Guacamole session refresh failed: HTTP ' + str(response.status))
+                            return
+                        await response.read()
+                    refreshed = time.monotonic()
+        except asyncio.CancelledError:
+            raise
+        except Exception:
+            self.fail('Guacamole session refresh failed; restart the bridge')
+
+    async def proxy(self, request):
+        if self.args.local_api_key and request.headers.get('Authorization') != 'Bearer ' + self.args.local_api_key:
+            return web.json_response({'error': {'message': 'Invalid local API key'}}, status=401)
+        if self.failed.is_set():
+            return web.json_response({'error': {'message': self.failure}}, status=503)
+        if request.query_string:
+            return web.json_response({'error': {'message': 'Query parameters are not supported'}}, status=400)
+        body = await request.read()
+        if len(self.requests) >= self.args.max_requests:
+            return web.json_response({'error': {'message': 'Bridge concurrency limit reached'}}, status=429)
+        ident = uuid.uuid4().hex
+        queue = asyncio.Queue(maxsize=16)
+        self.requests[ident] = queue
+        headers = {k: v for k, v in request.headers.items()
+                   if k.lower() in ('authorization', 'content-type', 'accept', 'x-request-id')}
+        # Keep framing/decompression simple and byte-for-byte at the local endpoint.
+        headers['Accept-Encoding'] = 'identity'
+        if self.args.upstream_api_key:
+            headers['Authorization'] = 'Bearer ' + self.args.upstream_api_key
+        response, complete = None, False
+        try:
+            async with asyncio.timeout(self.args.request_timeout):
+                await self.send_event({'type': 'request', 'id': ident, 'method': request.method,
+                                       'path': request.path, 'body': base64.b64encode(body).decode(),
+                                       'headers': headers})
+                while True:
+                    event = await self.next_event(queue, request)
+                    kind = event['type']
+                    if kind == 'headers':
+                        if response is not None:
+                            raise BridgeError('Duplicate upstream headers')
+                        response = web.StreamResponse(status=event['status'], headers=event['headers'])
+                        await response.prepare(request)
+                    elif kind == 'data':
+                        if response is None:
+                            raise BridgeError('Missing upstream headers')
+                        await response.write(base64.b64decode(event['body'], validate=True))
+                        await self.send_event({'type': 'credit', 'id': ident})
+                    elif kind == 'end':
+                        if response is None:
+                            raise BridgeError('Missing upstream response')
+                        await response.write_eof()
+                        complete = True
+                        return response
+                    elif kind == 'error':
+                        raise BridgeError(event['message'])
+        except (BridgeError, asyncio.TimeoutError, ConnectionError, aiohttp.ClientError) as exc:
+            status = 504 if isinstance(exc, asyncio.TimeoutError) else 502
+            message = str(exc) if isinstance(exc, BridgeError) else ('Request timed out' if status == 504 else 'Connection lost')
+            if response is None:
+                return web.json_response({'error': {'message': message, 'type': 'bridge_error'}}, status=status)
+            LOG.warning('Response interrupted: %s', message)
+            if request.transport:
+                request.transport.abort()
+            return response
+        finally:
+            self.requests.pop(ident, None)
+            if not complete and not self.failed.is_set():
+                with contextlib.suppress(Exception):
+                    await asyncio.wait_for(self.send_event({'type': 'cancel', 'id': ident}), timeout=5)
+
+    async def next_event(self, queue, request):
+        # Detect a disconnected HTTP consumer even while vLLM is still prefilling.
+        while True:
+            if request.transport is None or request.transport.is_closing():
+                raise ConnectionError('Local client disconnected')
+            try:
+                return await asyncio.wait_for(queue.get(), timeout=1)
+            except asyncio.TimeoutError:
+                if self.failed.is_set():
+                    raise BridgeError(self.failure)
+
+    async def close(self):
+        self.closing = True
+        if self.tunnel and self.ready.is_set() and not self.failed.is_set():
+            with contextlib.suppress(Exception):
+                await asyncio.wait_for(self.send_event({'type': 'shutdown'}), timeout=3)
+        if self.tunnel and not self.tunnel.closed:
+            with contextlib.suppress(Exception):
+                await asyncio.wait_for(self.tunnel.send('end', self.input_stream), timeout=2)
+        for task in (self.maintainer, self.reader):
+            if task:
+                task.cancel()
+        await asyncio.gather(*(t for t in (self.maintainer, self.reader) if t), return_exceptions=True)
+        if self.tunnel:
+            await self.tunnel.close()
+
+
+async def login(session, base, username, password, timeout):
+    async with session.post(base + 'api/tokens', data={'username': username, 'password': password},
+                            timeout=aiohttp.ClientTimeout(total=timeout), allow_redirects=False) as response:
+        if response.status != 200:
+            raise BridgeError('Guacamole login returned HTTP ' + str(response.status) +
+                              '. This tool supports the standard username/password login API; '
+                              'SSO/MFA or an external login portal requires adaptation.')
+        try:
+            payload = await response.json(content_type=None)
+            return payload['authToken']
+        except (ValueError, KeyError) as exc:
+            raise BridgeError('Login did not return a Guacamole authToken; check the URL base path') from exc
+
+
+async def serve(args):
+    base, conn, kind, source = parse_url(args.url, args.connection_id, args.data_source)
+    command = bootstrap(args)  # Validate helper availability/size before login.
+    del command
+    username = args.username or input('Guacamole username: ')
+    password = os.environ.get('GUAC_PASSWORD') or getpass.getpass('Guacamole password: ')
+    tls = ssl.create_default_context(cafile=args.ca_file)
+    if args.insecure:
+        tls.check_hostname = False
+        tls.verify_mode = ssl.CERT_NONE
+        LOG.warning('TLS verification disabled by --insecure')
+    timeout = aiohttp.ClientTimeout(total=None, sock_connect=args.connect_timeout)
+    connector = aiohttp.TCPConnector(ssl=tls)
+    async with aiohttp.ClientSession(connector=connector, timeout=timeout,
+                                     trust_env=True, auto_decompress=False,
+                                     headers={'Accept-Encoding': 'identity'}) as session:
+        token = await login(session, base, username, password, args.connect_timeout)
+        password = None
+        bridge = Bridge(args, session, base, conn, kind, source, token)
+        runner = None
+        try:
+            await bridge.start()
+            app = web.Application(client_max_size=args.max_body_mib * 1024 * 1024)
+            for path, method in PATHS.items():
+                app.router.add_route(method, path, bridge.proxy)
+
+            async def health(request):
+                return web.json_response({'ready': bridge.ready.is_set() and not bridge.failed.is_set()},
+                                         status=503 if bridge.failed.is_set() else 200)
+            app.router.add_get('/health', health)
+            runner = web.AppRunner(app, access_log=None, shutdown_timeout=5)
+            await runner.setup()
+            await web.TCPSite(runner, '127.0.0.1', args.port).start()
+            LOG.info('Local API: http://127.0.0.1:%s/v1 (Ctrl+C to stop)', args.port)
+            await bridge.failed.wait()
+            raise BridgeError(bridge.failure)
+        finally:
+            if runner:
+                await runner.cleanup()
+            await bridge.close()
+            with contextlib.suppress(Exception):
+                async with session.delete(base + 'api/tokens/' + urllib.parse.quote(token, safe=''),
+                                          timeout=aiohttp.ClientTimeout(total=5), allow_redirects=False) as response:
+                    await response.read()
+
+
+def cli():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--url', required=True, help='Guacamole URL, including #/client/...')
+    parser.add_argument('--username', help='Guacamole login username; otherwise prompted')
+    parser.add_argument('--port', type=int, default=8000, help='Local loopback port (default: 8000)')
+    parser.add_argument('--upstream', default='http://127.0.0.1:8000', help='Server-side loopback vLLM URL')
+    parser.add_argument('--connection-id', help='Override URL connection identifier')
+    parser.add_argument('--data-source', help='Override URL data source, e.g. mysql')
+    parser.add_argument('--transport', choices=('auto', 'websocket', 'http'), default='auto')
+    parser.add_argument('--server-command', default='~/.local/bin/guac-llm-server',
+                        help='Installed helper executable on server; absolute path recommended')
+    parser.add_argument('--startup-delay', type=float, default=2, help='Seconds for remote shell startup')
+    parser.add_argument('--connect-timeout', type=float, default=30)
+    parser.add_argument('--request-timeout', type=float, default=1800, help='Maximum request duration, seconds')
+    parser.add_argument('--max-requests', type=int, default=4)
+    parser.add_argument('--max-body-mib', type=int, default=16)
+    parser.add_argument('--ca-file', help='Corporate CA PEM file for HTTPS verification')
+    parser.add_argument('--insecure', action='store_true', help='Disable HTTPS certificate verification')
+    args = parser.parse_args()
+    args.upstream_api_key = os.environ.get('VLLM_API_KEY')
+    args.local_api_key = os.environ.get('BRIDGE_API_KEY')
+    if not 1 <= args.port <= 65535 or not 1 <= args.max_requests <= 16:
+        parser.error('Port must be 1..65535; --max-requests must be 1..16')
+    if min(args.connect_timeout, args.request_timeout, args.max_body_mib) <= 0 or args.startup_delay < 0:
+        parser.error('Timeouts/body limit must be positive; startup delay cannot be negative')
+    if args.max_body_mib > 16:
+        parser.error('--max-body-mib cannot exceed 16 (remote framing limit)')
+    upstream = urllib.parse.urlsplit(args.upstream)
+    if (upstream.scheme != 'http' or upstream.hostname not in ('127.0.0.1', 'localhost', '::1')
+            or upstream.username or upstream.password or upstream.query or upstream.fragment):
+        parser.error('--upstream must be HTTP on server loopback, with no credentials/query/fragment')
+    logging.basicConfig(level=logging.INFO, format='%(levelname)s: %(message)s')
+    try:
+        asyncio.run(serve(args))
+    except KeyboardInterrupt:
+        pass
+    except (BridgeError, OSError, aiohttp.ClientError, asyncio.TimeoutError) as exc:
+        # aiohttp exception strings can include authenticated tunnel URLs. Do not log them.
+        LOG.error('%s', str(exc) if isinstance(exc, BridgeError) else type(exc).__name__ +
+                  ': connection failed; check network, proxy, certificate, and local port')
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(cli())
+

guac_bridge/server.py

@@ -0,0 +1,160 @@
+"""Server-side stdin/stdout relay, launched inside a Guacamole SSH terminal."""
+import base64
+import http.client
+import json
+import os
+import socket
+import sys
+import threading
+import urllib.parse
+
+
+def run(config):
+    upstream = urllib.parse.urlsplit(config['upstream'])
+    if upstream.scheme != 'http' or upstream.hostname not in ('localhost', '127.0.0.1', '::1'):
+        raise ValueError('Upstream must be HTTP on server loopback')
+    stop = threading.Event()
+    lock = threading.Lock()
+    states = {}
+    state_lock = threading.Lock()
+    old_tty = None
+    if os.isatty(0):
+        import termios
+        import tty
+        old_tty = termios.tcgetattr(0)
+        tty.setraw(0)
+
+    def output(data):
+        with lock:
+            sys.stdout.buffer.write(data)
+            sys.stdout.buffer.flush()
+
+    def emit(event):
+        with lock:
+            if not stop.is_set():
+                sys.stdout.buffer.write(base64.b64encode(json.dumps(event, separators=(',', ':')).encode()) + b'\n')
+                sys.stdout.buffer.flush()
+
+    def worker(req, state):
+        ident = req['id']
+        conn = None
+        try:
+            path = req['path']
+            if path not in ('/v1/chat/completions', '/v1/completions', '/v1/models'):
+                raise ValueError('Unsupported endpoint')
+            conn = http.client.HTTPConnection(upstream.hostname, upstream.port or 80, timeout=5)
+            state['conn'] = conn
+            conn.connect()
+            state['sock'] = conn.sock
+            conn.sock.settimeout(config['timeout'])
+            if state['cancel'].is_set():
+                return
+            conn.request(req['method'], upstream.path.rstrip('/') + path,
+                         body=base64.b64decode(req['body'], validate=True), headers=req['headers'])
+            response = conn.getresponse()
+            headers = {k: v for k, v in response.getheaders()
+                       if k.lower() in ('content-type', 'content-encoding', 'retry-after', 'x-request-id')}
+            emit({'type': 'headers', 'id': ident, 'status': response.status, 'headers': headers})
+            while not state['cancel'].is_set():
+                # read1 returns available bytes; read(4096) would delay SSE tokens.
+                data = response.read1(4096)
+                if not data:
+                    break
+                while not state['cancel'].is_set():
+                    if state['credits'].acquire(timeout=1):
+                        break
+                if state['cancel'].is_set():
+                    break
+                emit({'type': 'data', 'id': ident, 'body': base64.b64encode(data).decode()})
+            if not state['cancel'].is_set():
+                emit({'type': 'end', 'id': ident})
+        except Exception as exc:
+            if not state['cancel'].is_set():
+                emit({'type': 'error', 'id': ident,
+                      'message': 'Upstream HTTP failed: ' + type(exc).__name__})
+        finally:
+            if conn:
+                conn.close()
+            with state_lock:
+                states.pop(ident, None)
+
+    def cancel(state):
+        state['cancel'].set()
+        sock = state.get('sock')
+        if sock:
+            try:
+                sock.shutdown(socket.SHUT_RDWR)
+            except OSError:
+                pass
+
+    def heartbeat():
+        while not stop.wait(10):
+            emit({'type': 'heartbeat'})
+
+    # Flag 2 enables per-frame autoflush, essential for readiness and SSE latency.
+    output(b'\x1b]482202;2;LLM\x07')
+    try:
+        emit({'type': 'ready', 'version': 1})
+        threading.Thread(target=heartbeat, daemon=True).start()
+        while True:
+            line = sys.stdin.buffer.readline(48 * 1024 * 1024)
+            if not line:
+                break
+            req = json.loads(base64.b64decode(line.strip(), validate=True))
+            kind = req.get('type')
+            if kind == 'shutdown':
+                break
+            ident = req.get('id')
+            if kind in ('credit', 'cancel'):
+                with state_lock:
+                    state = states.get(ident)
+                if state:
+                    if kind == 'credit':
+                        state['credits'].release()
+                    else:
+                        cancel(state)
+            elif kind == 'request':
+                with state_lock:
+                    if ident in states or len(states) >= config['max_requests']:
+                        emit({'type': 'error', 'id': ident, 'message': 'Remote concurrency limit'})
+                        continue
+                    state = {'credits': threading.Semaphore(8), 'cancel': threading.Event()}
+                    states[ident] = state
+                threading.Thread(target=worker, args=(req, state), daemon=True).start()
+    finally:
+        stop.set()
+        with state_lock:
+            active = list(states.values())
+        for state in active:
+            cancel(state)
+        # Serialize closing with writes from the daemon threads.
+        with lock:
+            sys.stdout.buffer.write(b'\x1b]482203;\x07')
+            sys.stdout.buffer.flush()
+        if old_tty is not None:
+            termios.tcsetattr(0, termios.TCSANOW, old_tty)
+
+
+def cli():
+    import argparse
+    parser = argparse.ArgumentParser(description='Relay vLLM HTTP through a Guacamole SSH terminal.')
+    parser.add_argument('--upstream', default='http://127.0.0.1:8000')
+    parser.add_argument('--request-timeout', type=float, default=1800)
+    parser.add_argument('--max-requests', type=int, default=4)
+    args = parser.parse_args()
+    url = urllib.parse.urlsplit(args.upstream)
+    if (url.scheme != 'http' or url.hostname not in ('localhost', '127.0.0.1', '::1')
+            or url.username or url.password or url.query or url.fragment):
+        parser.error('--upstream must be HTTP on loopback, without credentials/query/fragment')
+    if not 1 <= args.max_requests <= 16 or args.request_timeout <= 0:
+        parser.error('--max-requests must be 1..16 and --request-timeout must be positive')
+    try:
+        run({'upstream': args.upstream, 'timeout': args.request_timeout,
+             'max_requests': args.max_requests})
+    except (KeyboardInterrupt, BrokenPipeError, OSError):
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(cli())

guac_bridge/ssh_client.py

@@ -0,0 +1,216 @@
+"""Expose the remote server's SSH service on local loopback through Guacamole."""
+import argparse
+import asyncio
+import base64
+import contextlib
+import getpass
+import logging
+import os
+import shlex
+import ssl
+import time
+import urllib.parse
+import uuid
+
+import aiohttp
+
+from .client import Bridge, BridgeError, login, parse_url
+
+LOG = logging.getLogger('guac-ssh')
+CHUNK = 4096
+WINDOW = 8
+
+
+class SSHBridge(Bridge):
+    helper_name = 'guac-ssh-server'
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.credits = {}
+        self.connections = set()
+
+    def helper_command(self):
+        executable = ('"$HOME"/' + shlex.quote(self.args.server_command[2:])
+                      if self.args.server_command.startswith('~/') else shlex.quote(self.args.server_command))
+        values = ('--stdio', '--target-host', self.args.target_host, '--target-port', self.args.target_port,
+                  '--max-connections', self.args.max_connections, '--connect-timeout', self.args.connect_timeout)
+        command = executable + ' ' + ' '.join(shlex.quote(str(v)) for v in values) + '\n'
+        if len(command.encode()) > 3900:
+            raise BridgeError('Helper command exceeds terminal line limit')
+        return command.encode()
+
+    async def send_event(self, event):
+        # A connection cancellation must not interrupt a frame shared with other
+        # TCP connections, leaving an incomplete Base64 line in the remote PTY.
+        task = asyncio.create_task(super().send_event(event))
+        try:
+            await asyncio.shield(task)
+        except asyncio.CancelledError:
+            with contextlib.suppress(Exception):
+                await task
+            raise
+
+    def dispatch(self, event):
+        if event.get('type') == 'ready' and event.get('protocol') != 'ssh-tcp':
+            raise BridgeError('Expected guac-ssh-server; incorrect remote helper')
+        if event.get('type') == 'credit':
+            self.last_seen = time.monotonic()
+            semaphore = self.credits.get(event.get('id'))
+            if semaphore:
+                semaphore.release()
+        else:
+            super().dispatch(event)
+
+    async def accept(self, reader, writer):
+        task = asyncio.current_task()
+        if self.failed.is_set() or self.closing or len(self.requests) >= self.args.max_connections:
+            writer.close()
+            with contextlib.suppress(Exception):
+                await writer.wait_closed()
+            return
+        self.connections.add(task)
+        ident = uuid.uuid4().hex
+        queue = asyncio.Queue(maxsize=WINDOW + 4)
+        self.requests[ident] = queue
+        self.credits[ident] = asyncio.BoundedSemaphore(WINDOW)
+        tasks = []
+        try:
+            await self.send_event({'type': 'open', 'id': ident})
+            event = await self.wait_for(queue.get(), self.args.connect_timeout)
+            if event['type'] != 'opened':
+                raise BridgeError(event.get('message', 'SSH target did not open'))
+
+            async def upload():
+                while True:
+                    await self.credits[ident].acquire()
+                    data = await reader.read(CHUNK)
+                    if not data:
+                        self.credits[ident].release()
+                        await self.send_event({'type': 'eof', 'id': ident})
+                        return
+                    await self.send_event({'type': 'data', 'id': ident,
+                                           'body': base64.b64encode(data).decode()})
+
+            async def download():
+                while True:
+                    event = await queue.get()
+                    kind = event['type']
+                    if kind == 'data':
+                        data = base64.b64decode(event['body'], validate=True)
+                        if len(data) > CHUNK:
+                            raise BridgeError('TCP frame exceeds limit')
+                        writer.write(data)
+                        await writer.drain()
+                        await self.send_event({'type': 'credit', 'id': ident})
+                    elif kind in ('eof', 'closed'):
+                        if writer.can_write_eof():
+                            writer.write_eof()
+                            await writer.drain()
+                        return
+                    elif kind == 'error':
+                        raise BridgeError(event['message'])
+                    else:
+                        raise BridgeError('Unexpected TCP relay event')
+
+            tasks = [asyncio.create_task(upload()), asyncio.create_task(download())]
+            await asyncio.gather(*tasks)
+        except asyncio.CancelledError:
+            raise
+        except (BridgeError, ConnectionError, OSError, asyncio.TimeoutError) as exc:
+            LOG.warning('%s', str(exc) if isinstance(exc, BridgeError) else 'SSH TCP connection interrupted')
+            if writer.transport:
+                writer.transport.abort()
+        finally:
+            for child in tasks:
+                child.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+            if not self.failed.is_set() and self.tunnel and not self.tunnel.closed:
+                with contextlib.suppress(Exception):
+                    await asyncio.wait_for(self.send_event({'type': 'close', 'id': ident}), 5)
+            self.requests.pop(ident, None)
+            self.credits.pop(ident, None)
+            writer.close()
+            with contextlib.suppress(Exception):
+                await asyncio.wait_for(writer.wait_closed(), 2)
+            self.connections.discard(task)
+
+    async def close(self):
+        self.closing = True
+        tasks = list(self.connections)
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(*tasks, return_exceptions=True)
+        await super().close()
+
+
+async def serve(args):
+    base, conn, kind, source = parse_url(args.url, args.connection_id, args.data_source)
+    username = args.username or input('Guacamole username: ')
+    password = os.environ.get('GUAC_PASSWORD') or getpass.getpass('Guacamole password: ')
+    tls = ssl.create_default_context(cafile=args.ca_file)
+    if args.insecure:
+        tls.check_hostname = False
+        tls.verify_mode = ssl.CERT_NONE
+        LOG.warning('TLS verification disabled by --insecure')
+    connector = aiohttp.TCPConnector(ssl=tls)
+    async with aiohttp.ClientSession(connector=connector, trust_env=True, auto_decompress=False,
+                                     timeout=aiohttp.ClientTimeout(total=None, sock_connect=args.connect_timeout),
+                                     headers={'Accept-Encoding': 'identity'}) as session:
+        token = await login(session, base, username, password, args.connect_timeout)
+        password = None
+        bridge = SSHBridge(args, session, base, conn, kind, source, token)
+        listener = None
+        try:
+            await bridge.start()
+            listener = await asyncio.start_server(bridge.accept, '127.0.0.1', args.port)
+            LOG.info('SSH bridge: 127.0.0.1:%s -> server %s:%s (Ctrl+C to stop)',
+                     args.port, args.target_host, args.target_port)
+            await bridge.failed.wait()
+            raise BridgeError(bridge.failure)
+        finally:
+            if listener:
+                listener.close()
+            await bridge.close()
+            if listener:
+                await listener.wait_closed()
+            with contextlib.suppress(Exception):
+                async with session.delete(base + 'api/tokens/' + urllib.parse.quote(token, safe=''),
+                                          timeout=aiohttp.ClientTimeout(total=5), allow_redirects=False) as response:
+                    await response.read()
+
+
+def cli():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--url', required=True, help='Full Guacamole connection URL')
+    parser.add_argument('--username', help='Guacamole username; otherwise prompted')
+    parser.add_argument('--port', type=int, default=2222, help='Local loopback listener port')
+    parser.add_argument('--target-host', choices=('127.0.0.1', 'localhost', '::1'), default='127.0.0.1')
+    parser.add_argument('--target-port', type=int, default=22, help='Server-side loopback SSH port')
+    parser.add_argument('--max-connections', type=int, default=8)
+    parser.add_argument('--server-command', default='~/.local/bin/guac-ssh-server', help='Remote helper executable path')
+    parser.add_argument('--connection-id')
+    parser.add_argument('--data-source')
+    parser.add_argument('--transport', choices=('auto', 'websocket', 'http'), default='auto')
+    parser.add_argument('--startup-delay', type=float, default=2)
+    parser.add_argument('--connect-timeout', type=float, default=30)
+    parser.add_argument('--ca-file', help='Corporate CA PEM bundle')
+    parser.add_argument('--insecure', action='store_true', help='Disable Guacamole TLS verification')
+    args = parser.parse_args()
+    if not (1 <= args.port <= 65535 and 1 <= args.target_port <= 65535 and 1 <= args.max_connections <= 16):
+        parser.error('Ports must be 1..65535 and connection limit must be 1..16')
+    if args.connect_timeout <= 0 or args.startup_delay < 0:
+        parser.error('Timeout must be positive and startup delay cannot be negative')
+    logging.basicConfig(level=logging.INFO, format='%(levelname)s: %(message)s')
+    try:
+        asyncio.run(serve(args))
+    except KeyboardInterrupt:
+        pass
+    except (BridgeError, OSError, aiohttp.ClientError, asyncio.TimeoutError) as exc:
+        LOG.error('%s', str(exc) if isinstance(exc, BridgeError) else type(exc).__name__ +
+                  ': check network, proxy, TLS trust, and local port')
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(cli())

guac_bridge/ssh_server.py

@@ -0,0 +1,187 @@
+"""Binary TCP relay to a loopback SSH service, over a Guacamole terminal."""
+import argparse
+import asyncio
+import base64
+import contextlib
+import json
+import os
+import signal
+import sys
+import threading
+
+CHUNK = 4096
+WINDOW = 8
+
+
+async def relay(args):
+    events = asyncio.Queue(maxsize=64)
+    channels = {}
+    loop = asyncio.get_running_loop()
+    stopping = threading.Event()
+
+    def emit(event):
+        data = base64.b64encode(json.dumps(event, separators=(',', ':')).encode())
+        sys.stdout.buffer.write(data + b'\n')
+        sys.stdout.buffer.flush()
+
+    def stdin_reader():
+        try:
+            while not stopping.is_set():
+                line = sys.stdin.buffer.readline(65536)
+                if not line:
+                    event = {'type': 'shutdown'}
+                else:
+                    if not line.endswith(b'\n'):
+                        raise ValueError('Frame too large')
+                    event = json.loads(base64.b64decode(line.strip(), validate=True))
+                future = asyncio.run_coroutine_threadsafe(events.put(event), loop)
+                future.result()
+                if event.get('type') == 'shutdown':
+                    return
+        except Exception:
+            if not stopping.is_set() and not loop.is_closed():
+                asyncio.run_coroutine_threadsafe(events.put({'type': 'shutdown'}), loop)
+
+    async def connection(ident, state):
+        writer = None
+        tasks = []
+        try:
+            reader, writer = await asyncio.wait_for(
+                asyncio.open_connection(args.target_host, args.target_port), args.connect_timeout)
+            emit({'type': 'opened', 'id': ident})
+
+            async def receive_tcp():
+                while True:
+                    await state['credits'].acquire()
+                    data = await reader.read(CHUNK)
+                    if not data:
+                        state['credits'].release()
+                        emit({'type': 'eof', 'id': ident})
+                        return
+                    emit({'type': 'data', 'id': ident, 'body': base64.b64encode(data).decode()})
+
+            async def send_tcp():
+                while True:
+                    data = await state['input'].get()
+                    if data is None:
+                        if writer.can_write_eof():
+                            writer.write_eof()
+                            await writer.drain()
+                        return
+                    writer.write(data)
+                    await writer.drain()
+                    emit({'type': 'credit', 'id': ident})
+
+            tasks = [asyncio.create_task(receive_tcp()), asyncio.create_task(send_tcp())]
+            await asyncio.gather(*tasks)
+            emit({'type': 'closed', 'id': ident})
+        except asyncio.CancelledError:
+            raise
+        except Exception as exc:
+            emit({'type': 'error', 'id': ident,
+                  'message': 'SSH target connection failed: ' + type(exc).__name__})
+        finally:
+            for task in tasks:
+                task.cancel()
+            await asyncio.gather(*tasks, return_exceptions=True)
+            if writer:
+                writer.close()
+                with contextlib.suppress(Exception):
+                    await asyncio.wait_for(writer.wait_closed(), 2)
+            channels.pop(ident, None)
+
+    async def heartbeat():
+        while True:
+            await asyncio.sleep(10)
+            emit({'type': 'heartbeat'})
+
+    # LLM is the established transport pipe name, shared by both relay modes.
+    sys.stdout.buffer.write(b'\x1b]482202;2;LLM\x07')
+    sys.stdout.buffer.flush()
+    emit({'type': 'ready', 'version': 1, 'protocol': 'ssh-tcp'})
+    main = asyncio.current_task()
+    for sig in (signal.SIGTERM, signal.SIGHUP):
+        loop.add_signal_handler(sig, main.cancel)
+    thread = threading.Thread(target=stdin_reader, daemon=True)
+    thread.start()
+    pulse = asyncio.create_task(heartbeat())
+    try:
+        while True:
+            event = await events.get()
+            kind, ident = event.get('type'), event.get('id')
+            if kind == 'shutdown':
+                break
+            if kind == 'open':
+                if not isinstance(ident, str) or not ident or len(ident) > 64:
+                    raise ValueError('Invalid connection ID')
+                if ident in channels:
+                    raise ValueError('Duplicate connection ID')
+                if len(channels) >= args.max_connections:
+                    emit({'type': 'error', 'id': ident, 'message': 'SSH connection limit reached'})
+                    continue
+                state = {'input': asyncio.Queue(maxsize=WINDOW + 1),
+                         'credits': asyncio.BoundedSemaphore(WINDOW), 'eof': False}
+                channels[ident] = state
+                state['task'] = asyncio.create_task(connection(ident, state))
+                continue
+            state = channels.get(ident)
+            if state is None:
+                continue
+            if kind == 'data':
+                data = base64.b64decode(event['body'], validate=True)
+                if len(data) > CHUNK or state['eof']:
+                    raise ValueError('Invalid TCP data frame')
+                state['input'].put_nowait(data)
+            elif kind == 'credit':
+                state['credits'].release()
+            elif kind == 'eof':
+                if state['eof']:
+                    raise ValueError('Duplicate TCP EOF')
+                state['eof'] = True
+                state['input'].put_nowait(None)
+            elif kind == 'close':
+                state['task'].cancel()
+    finally:
+        stopping.set()
+        pulse.cancel()
+        tasks = [state['task'] for state in list(channels.values())]
+        for task in tasks:
+            task.cancel()
+        await asyncio.gather(pulse, *tasks, return_exceptions=True)
+        sys.stdout.buffer.write(b'\x1b]482203;\x07')
+        sys.stdout.buffer.flush()
+        for sig in (signal.SIGTERM, signal.SIGHUP):
+            loop.remove_signal_handler(sig)
+
+
+def cli():
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('--stdio', action='store_true', help='Run the machine protocol; supplied by guac-ssh-client')
+    parser.add_argument('--target-host', choices=('127.0.0.1', 'localhost', '::1'), default='127.0.0.1')
+    parser.add_argument('--target-port', type=int, default=22)
+    parser.add_argument('--connect-timeout', type=float, default=30)
+    parser.add_argument('--max-connections', type=int, default=8)
+    args = parser.parse_args()
+    if not args.stdio:
+        parser.error('This helper is started automatically by guac-ssh-client. Do not run it manually.')
+    if not 1 <= args.target_port <= 65535 or not 1 <= args.max_connections <= 16 or args.connect_timeout <= 0:
+        parser.error('Invalid target port, connection limit (1..16), or timeout')
+    old = None
+    try:
+        if os.isatty(0):
+            import termios
+            import tty
+            old = termios.tcgetattr(0)
+            tty.setraw(0)
+        asyncio.run(relay(args))
+    except (asyncio.CancelledError, KeyboardInterrupt, BrokenPipeError, OSError, ValueError):
+        return 1
+    finally:
+        if old is not None:
+            with contextlib.suppress(OSError):
+                termios.tcsetattr(0, termios.TCSANOW, old)
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(cli())

guac_bridge-0.2.0.dist-info/METADATA

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: guac-bridge
+Version: 0.2.0
+Summary: Bridge remote LLM APIs and SSH over an Apache Guacamole terminal
+License-Expression: MIT
+Project-URL: Repository, https://github.com/himbeles/guac-bridge
+Project-URL: Issues, https://github.com/himbeles/guac-bridge/issues
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4,>=3.10
+Dynamic: license-file
+
+# Guac Bridge
+
+Access an OpenAI-compatible endpoint or SSH service on a server through its
+Guacamole web terminal.
+
+## Install
+
+Install on both your client computer and the server. Requires Python 3.11+ and
+[uv](https://docs.astral.sh/uv/).
+
+```shell
+uv tool install guac-bridge
+uv tool update-shell
+```
+
+The client starts the appropriate server helper automatically. Keep the client
+running while using the bridge; stop it with **Ctrl+C**.
+
+For the commands below, copy the full URL from your browser after opening the
+desired Guacamole connection. Replace `CLIENT_ID` and `YOUR_USERNAME` with
+your connection details. Your Guacamole password is prompted.
+
+## Usage: LLM bridge
+
+The server's OpenAI-compatible endpoint should be available at
+`http://127.0.0.1:8000`.
+
+On your client computer:
+
+```shell
+guac-llm-client --url "https://guacamole.example.com/#/client/CLIENT_ID" --username YOUR_USERNAME
+```
+
+Configure your LLM application with:
+
+| Setting | Value |
+| --- | --- |
+| OpenAI base URL | `http://127.0.0.1:8000/v1` |
+| Chat completions URL | `http://127.0.0.1:8000/v1/chat/completions` |
+| Model | A model ID from `/v1/models` |
+| API key | The key required by the server endpoint, or a placeholder if none is required |
+
+Requests, streamed responses, and the application's API key are forwarded to
+the server endpoint.
+
+Use `--upstream http://127.0.0.1:9000` for a different server-side endpoint
+(omit `/v1`), or `--port 18000` for a different local port.
+
+## Usage: SSH bridge
+
+The server's SSH service should be reachable at `127.0.0.1:22`.
+
+On your client computer:
+
+```shell
+guac-ssh-client --url "https://guacamole.example.com/#/client/CLIENT_ID" --username YOUR_USERNAME
+```
+
+In another local terminal:
+
+```shell
+ssh -p 2222 serveruser@127.0.0.1
+```
+
+Use the server's SSH username and its usual password or SSH key. SSH
+authentication and host-key verification are handled by your SSH client.
+SCP and SFTP work through the same local port.
+
+To forward the server's OpenAI-compatible endpoint through SSH:
+
+```shell
+ssh -p 2222 -N -L 8000:127.0.0.1:8000 serveruser@127.0.0.1
+```
+
+Use `--target-port` to select a different server-side SSH port and `--port`
+to change the local listener.
+
+Both bridges support `--ca-file company-ca.pem` for a custom certificate
+authority and `--transport http` to use Guacamole's HTTP tunnel.
+If a helper is installed outside `~/.local/bin/`, pass its full path with
+`--server-command`. Run either client with `--help` for all options.
+
+## Contribution
+
+Submit issues and pull requests on
+[GitHub](https://github.com/himbeles/guac-bridge).
+Include tests for behavior changes.
+
+From a repository checkout, run the test suite in an environment with Bash and
+PTY support:
+
+```shell
+uv run python -m unittest discover -s tests -v
+```
+
+## Architecture
+
+Each client logs into Guacamole and starts its matching server helper inside
+the terminal session. Framed, Base64-encoded messages travel through Guacamole's
+input and output pipes.
+
+| Bridge | Local listener | Server helper |
+| --- | --- | --- |
+| LLM | OpenAI-compatible HTTP API | Forwards requests and streamed responses to the server endpoint |
+| SSH | TCP port for your SSH client | Relays bytes to the server's SSH service |
+
+Listeners bind to local loopback. Helpers connect to services on the server's
+loopback interface, so no additional inbound server port is needed. Per-connection
+flow control bounds buffering; disconnecting Guacamole closes active connections.

guac_bridge-0.2.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+guac_bridge/__init__.py,sha256=wvkRrh7soGDfH5EAe7WrQtTiyy54VwwkWDyle5cJ6X8,23
+guac_bridge/client.py,sha256=4oMy9TyVr_6w6ID-YiLNL1D4LG9H2Ncl8VfU5kLDwdQ,28128
+guac_bridge/server.py,sha256=qm-WZaVzDeqSo8xuLCKzc6eXYEXHJYpStNbGyqq9U4Y,6316
+guac_bridge/ssh_client.py,sha256=2w5VgONffDBzYTyJjTPKBBzdj6eJ95gKBMe98e7PnfY,9839
+guac_bridge/ssh_server.py,sha256=RBOIge-iWrZAI3qvlqyBTaj_rwoVhmnPvZv_-2RkuJY,7414
+guac_bridge-0.2.0.dist-info/licenses/LICENSE,sha256=ESYyLizI0WWtxMeS7rGVcX3ivMezm-HOd5WdeOh-9oU,1056
+guac_bridge-0.2.0.dist-info/METADATA,sha256=BOFsZ0Y_gll886HE3vza095-P-WX9BYUxdv6Q2cimeY,3900
+guac_bridge-0.2.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+guac_bridge-0.2.0.dist-info/entry_points.txt,sha256=N__qZ5gDuoF519ypppTgsHxR7zVtlknQzfDafRrorAY,190
+guac_bridge-0.2.0.dist-info/top_level.txt,sha256=0sZAaWVnM-Sbwkgih1UEJ_wAOVJY6RQ3tlyvxUvjrN8,12
+guac_bridge-0.2.0.dist-info/RECORD,,

guac_bridge-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

guac_bridge-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,5 @@
+[console_scripts]
+guac-llm-client = guac_bridge.client:cli
+guac-llm-server = guac_bridge.server:cli
+guac-ssh-client = guac_bridge.ssh_client:cli
+guac-ssh-server = guac_bridge.ssh_server:cli

guac_bridge-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

guac_bridge-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+guac_bridge