hello-127 0.1.1__py3-none-any.whl

hello_127/__init__.py

@@ -0,0 +1 @@
+"""hello-127: carry TCP over a container's standard streams to Ollama on loopback."""

hello_127/args.py

@@ -0,0 +1,205 @@
+"""The command line's vocabulary: the parser, its subparsers, and the version line."""
+import argparse
+import ipaddress
+import sys
+from collections import namedtuple
+from importlib import metadata
+
+from hello_127 import cli_query, cli_tunnel, launch
+
+PROG = "hello-127"
+
+PATHS = """\
+paths:
+  RUNTIME   `docker` or `container`, the runtime that runs CONTAINER.
+  CONTAINER the name or id of a running container.
+  RUNTIME and CONTAINER come right after COMMAND, then options in any order."""
+
+MONOCHROME = {"color": False} if sys.version_info >= (3, 14) else {}
+
+LOOPBACK = "127.0.0.1"
+OLLAMA_PORT = 11434
+
+Forward = namedtuple("Forward", "bind port host hostport")
+"""Where the helper listens inside, and what the Mac dials for each connection."""
+
+Endpoint = namedtuple("Endpoint", "address port")
+"""An address and a port, for `ollama-query` to dial inside the container."""
+
+DEFAULT_FORWARD = Forward(LOOPBACK, OLLAMA_PORT, LOOPBACK, OLLAMA_PORT)
+DEFAULT_ENDPOINT = Endpoint(LOOPBACK, OLLAMA_PORT)
+
+
+def leading_paths(tokens):
+    """Return the tokens ahead of the first flag."""
+    paths = []
+    for token in tokens:
+        if token.startswith("-"):
+            break
+        paths.append(token)
+    return paths
+
+
+def installed_version():
+    """Return the version of the installed hello-127 distribution."""
+    try:
+        return metadata.version("hello-127")
+    except metadata.PackageNotFoundError:
+        return "unknown (not installed)"
+
+
+def version_line():
+    """Return the program name and the installed version on one line."""
+    return f"{PROG} {installed_version()}"
+
+
+def loopback(text):
+    """Return `text` as a loopback IPv4 address, or refuse it as a bad value."""
+    try:
+        address = ipaddress.IPv4Address(text)
+    except ValueError:
+        raise argparse.ArgumentTypeError(f"not an IPv4 address: {text!r}") from None
+    if not address.is_loopback:
+        raise argparse.ArgumentTypeError(f"not a loopback address: {text!r}")
+    return str(address)
+
+
+def port_number(text):
+    """Return `text` as a TCP port from 1 to 65535, or refuse it as a bad value."""
+    if not (text.isascii() and text.isdigit() and 0 < int(text) < 65536):
+        raise argparse.ArgumentTypeError(f"not a port: {text!r}")
+    return int(text)
+
+
+def forward_spec(text):
+    """Read `[BIND:]PORT:HOST:HOSTPORT` into a Forward. BIND defaults to loopback."""
+    parts = text.split(":")
+    if len(parts) == 3:
+        parts.insert(0, LOOPBACK)
+    if len(parts) != 4:
+        raise argparse.ArgumentTypeError(f"expected [BIND:]PORT:HOST:HOSTPORT: {text!r}")
+    bind, port, host, hostport = parts
+    return Forward(loopback(bind), port_number(port), loopback(host), port_number(hostport))
+
+
+def endpoint_spec(text):
+    """Read `ADDRESS:PORT` into an Endpoint."""
+    parts = text.split(":")
+    if len(parts) != 2:
+        raise argparse.ArgumentTypeError(f"expected ADDRESS:PORT: {text!r}")
+    address, port = parts
+    return Endpoint(loopback(address), port_number(port))
+
+
+class StoreOnce(argparse.Action):
+    """Store a flag's value, and refuse the flag given a second time."""
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        """Store `values`, unless an earlier occurrence already replaced the default."""
+        if getattr(namespace, self.dest) is not self.default:
+            raise argparse.ArgumentError(self, "given more than once")
+        setattr(namespace, self.dest, values)
+
+
+class AppendForward(argparse.Action):
+    """Collect each --forward in order, and refuse a listener given twice."""
+
+    def __call__(self, parser, namespace, values, option_string=None):
+        """Append `values`, starting a fresh list in place of the default."""
+        forwards = getattr(namespace, self.dest)
+        if forwards is self.default:
+            forwards = []
+        if any(forward[:2] == values[:2] for forward in forwards):
+            raise argparse.ArgumentError(
+                self, f"listener {values.bind}:{values.port} given twice"
+            )
+        setattr(namespace, self.dest, [*forwards, values])
+
+
+def add_runtime_slots(command):
+    """Add the RUNTIME and CONTAINER positionals that both commands read."""
+    paths = command.add_argument_group("paths")
+    paths.add_argument(
+        "runtime",
+        nargs="?",
+        choices=sorted(launch.EXEC),
+        metavar="RUNTIME",
+        help="`docker` or `container`",
+    )
+    paths.add_argument(
+        "container", nargs="?", metavar="CONTAINER", help="a running container"
+    )
+    return command
+
+
+def add_tunnel(subparsers):
+    """Add the `tunnel` subparser and return it."""
+    tunnel = add_runtime_slots(
+        subparsers.add_parser(
+            "tunnel", help=cli_tunnel.HELP, usage=cli_tunnel.USAGE, allow_abbrev=False
+        )
+    )
+    tunnel.add_argument(
+        "--forward",
+        type=forward_spec,
+        action=AppendForward,
+        default=[DEFAULT_FORWARD],
+        dest="forwards",
+        metavar="SPEC",
+        help="listen on BIND:PORT inside and dial HOST:HOSTPORT on the Mac, "
+        "as [BIND:]PORT:HOST:HOSTPORT, all loopback; repeat for more "
+        "(default: 127.0.0.1:11434:127.0.0.1:11434)",
+    )
+    return tunnel
+
+
+def add_ollama_query(subparsers):
+    """Add the `ollama-query` subparser and return it."""
+    query = add_runtime_slots(
+        subparsers.add_parser(
+            "ollama-query",
+            help=cli_query.HELP,
+            usage=cli_query.USAGE,
+            allow_abbrev=False,
+        )
+    )
+    query.add_argument(
+        "--connect",
+        type=endpoint_spec,
+        action=StoreOnce,
+        default=DEFAULT_ENDPOINT,
+        metavar="ADDRESS:PORT",
+        help="where the tunnel listens inside, loopback (default: 127.0.0.1:11434)",
+    )
+    return query
+
+
+def build_parser():
+    """Build the top-level parser with every command."""
+    parser = argparse.ArgumentParser(
+        prog=PROG,
+        usage="\n       ".join([cli_tunnel.USAGE, cli_query.USAGE, f"{PROG} version"]),
+        epilog=PATHS,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+        allow_abbrev=False,
+        **MONOCHROME,
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=version_line(),
+        help="print the installed version and exit",
+    )
+    subparsers = parser.add_subparsers(dest="command", metavar="COMMAND", required=True)
+    add_tunnel(subparsers)
+    add_ollama_query(subparsers)
+    subparsers.add_parser(
+        "version", help="print the installed version and exit", allow_abbrev=False
+    )
+    return parser
+
+
+def command_help(add_command):
+    """Return one command's own `--help` text, as argparse prints it."""
+    subparsers = argparse.ArgumentParser(prog=PROG, **MONOCHROME).add_subparsers()
+    return add_command(subparsers).format_help()

hello_127/cli.py

@@ -0,0 +1,146 @@
+"""
+# ==============================================
+# East Van AI -- AI for the rest of us!
+# https://github.com/east-van-ai/hello-127
+# contact: east-van-ai@proton.me
+# license: MIT
+# ==============================================
+
+        hello-127
+
+Carries TCP over a container's standard streams, so a container with no
+network reaches Ollama on the Mac's 127.0.0.1. A helper inside listens on
+127.0.0.1:11434; this side dials Ollama for every connection it reports.
+Reach for `tunnel`, then `ollama-query` to try it.
+
+Run a command with nothing after it for its own page.
+
+piped input:
+    hello-127 reads none.
+
+exit codes:
+    0:     success, and documentation
+    1:     hello-127's own error: a missing CONTAINER, a stray word after it,
+           the runtime not on PATH, or the helper or the query exiting
+           with an error
+    2:     an unknown command, an unknown option, or a bad value
+"""
+import sys
+from collections import namedtuple
+
+from hello_127 import args, cli_query, cli_tunnel, errors
+
+# argparse exits 2 itself, so EXIT_ARGPARSE never returns through main.
+EXIT_OK = 0
+EXIT_ERROR = 1
+EXIT_ARGPARSE = 2
+
+
+def command_page(module, add_command):
+    """Return a command's answer to its bare word: its docstring, then its --help."""
+    doc = module.__doc__.strip("\n")  # not strip(): the title's indent is layout
+    return f"{doc}\n\n{args.command_help(add_command).rstrip()}"
+
+
+Command = namedtuple("Command", "bare usage slots action")
+"""A command word's answer to being typed alone, its usage line, the path slots it
+reads, and the action a full invocation runs.
+
+`bare` returns the text for the bare word; `action` runs the command. For `version`,
+both read from `version_line`, since running the command answers the bare word.
+"""
+
+COMMANDS = {
+    "tunnel": Command(
+        lambda: command_page(cli_tunnel, args.add_tunnel),
+        cli_tunnel.USAGE,
+        cli_tunnel.SLOTS,
+        lambda paths, parsed: cli_tunnel.run(*paths, parsed),
+    ),
+    "ollama-query": Command(
+        lambda: command_page(cli_query, args.add_ollama_query),
+        cli_query.USAGE,
+        cli_query.SLOTS,
+        lambda paths, parsed: cli_query.run(*paths, parsed),
+    ),
+    "version": Command(
+        args.version_line,
+        "hello-127 version",
+        (),
+        lambda paths, parsed: print(args.version_line()),
+    ),
+}
+
+
+def usage_error(usage, message):
+    """Report a command line the tool could not read, with the matching usage."""
+    sys.stdout.flush()
+    print(f"hello-127: {message}", file=sys.stderr)
+    print(f"Usage: {usage}", file=sys.stderr)
+    return EXIT_ERROR
+
+
+def readiness_error(message):
+    """Report what the run needed and did not find, with no usage line."""
+    sys.stdout.flush()
+    print(f"hello-127: {message}", file=sys.stderr)
+    return EXIT_ERROR
+
+
+def runtime_error(message):
+    """Report a run that stopped partway, naming what was written."""
+    sys.stdout.flush()
+    print(f"hello-127: {message}", file=sys.stderr)
+    return EXIT_ERROR
+
+
+def main(argv=None):
+    """Parse arguments, run the matching command, return an exit code."""
+    tokens = list(sys.argv[1:] if argv is None else argv)
+
+    if not tokens:
+        print(f"{__doc__.strip()}\n\n{args.build_parser().format_help().rstrip()}")
+        return EXIT_OK
+
+    # A command word and nothing else is a question, and its own page answers.
+    if len(tokens) == 1 and tokens[0] in COMMANDS:
+        print(COMMANDS[tokens[0]].bare())
+        return EXIT_OK
+
+    parser = args.build_parser()
+    parsed, extras = parser.parse_known_args(tokens)
+
+    if any(extra.startswith("-") for extra in extras):
+        parser.parse_args(tokens)  # argparse names the flag better, exit 2
+
+    paths = args.leading_paths(tokens[1:])
+
+    command = COMMANDS[parsed.command]
+
+    if len(paths) < len(command.slots):
+        needed = " and ".join(command.slots)
+        if len(command.slots) > 1:
+            needed = f"both {needed}"
+        return usage_error(command.usage, f"{parsed.command} needs {needed}")
+
+    # A word past the slots is a stray, and so is one argparse left over after a flag.
+    strays = paths[len(command.slots) :] or extras
+    if strays:
+        last = command.slots[-1] if command.slots else "it"
+        return usage_error(
+            command.usage,
+            f"{parsed.command} takes nothing after {last}: {strays[0]!r}",
+        )
+
+    try:
+        command.action(paths, parsed)
+    except errors.ReadinessError as failure:
+        return readiness_error(str(failure))
+    except errors.RuntimeFailure as failure:
+        return runtime_error(str(failure))
+
+    return EXIT_OK
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hello_127/cli_query.py

@@ -0,0 +1,41 @@
+"""
+        hello-127 -- Ollama Query
+
+https://github.com/east-van-ai/hello-127
+
+Asks Ollama one question from inside a running container, and prints the
+answer as it streams. The program runs in the container and dials
+127.0.0.1:11434, or the loopback ADDRESS:PORT given to --connect, so it
+reaches Ollama only through a running `tunnel` listening there.
+
+The model is Cohere's Tiny Aya, hf.co/CohereLabs/tiny-aya-global-GGUF:Q4_K_M,
+and the prompt is fixed. It is a probe, not a client.
+
+RUNTIME `docker` runs the program with `docker exec`, and `container` with
+Apple Container's `container exec`. The container must have python3, 3.10 or
+newer.
+
+With no tunnel running, the program says nothing answers on that
+address and port, and exits 1.
+"""
+import subprocess
+
+from hello_127 import errors, launch, query
+
+HELP = "ask Ollama one question from inside a container, through the tunnel"
+USAGE = "hello-127 ollama-query RUNTIME CONTAINER [--connect ADDRESS:PORT]"
+SLOTS = ("RUNTIME", "CONTAINER")
+
+
+def run(runtime, name, parsed):
+    """Run the query inside container `name`, streaming its answer to stdout."""
+    program = launch.source(query, "ask", *parsed.connect)
+    command = launch.exec_command(runtime, name, program)
+    try:
+        code = subprocess.run(command).returncode
+    except FileNotFoundError:
+        raise errors.ReadinessError(f"{command[0]} is not on PATH") from None
+    except KeyboardInterrupt:
+        raise errors.RuntimeFailure("the query was interrupted") from None
+    if code:
+        raise errors.RuntimeFailure(f"the query exited with code {code}")

hello_127/cli_tunnel.py

@@ -0,0 +1,49 @@
+"""
+        hello-127 -- Tunnel
+
+https://github.com/east-van-ai/hello-127
+
+Starts a helper inside a running container and relays its connections to
+a service on the Mac's loopback. By default the helper listens on
+127.0.0.1:11434 inside, and the Mac dials Ollama on 127.0.0.1:11434, so a
+program in the container reaches Ollama as if it were local, even with
+--network none.
+
+--forward changes both ends, in `ssh -L`'s shape: BIND:PORT is where the
+helper listens inside, and HOST:HOSTPORT is what the Mac dials. BIND may be
+left out, and is then 127.0.0.1. Every address must be loopback, 127.0.0.1
+to 127.255.255.255. The Mac answers only on the 127.x addresses its lo0
+carries, by default 127.0.0.1 alone. Another HOST leaves each connection
+hanging until macOS gives up, after about 75 seconds.
+
+--forward may repeat, once per listener, and one helper carries them all.
+Two forwards may share a HOST:HOSTPORT, but not a BIND:PORT. A HOST that
+hangs stalls every forward, not just its own, until macOS gives up.
+
+RUNTIME `docker` runs the helper with `docker exec -i`, and `container` with
+Apple Container's `container exec -i`. The container must already be running
+and have python3, 3.10 or newer.
+
+The tunnel runs until Ctrl-C, which closes the helper's input so it exits.
+If the helper lingers for 5 seconds, the exec is killed.
+"""
+import asyncio
+
+from hello_127 import errors, host, launch, wire
+
+HELP = "relay a container's loopback port to the Mac's, 11434 by default"
+USAGE = "hello-127 tunnel RUNTIME CONTAINER [--forward SPEC]..."
+SLOTS = ("RUNTIME", "CONTAINER")
+
+
+def run(runtime, name, parsed):
+    """Run the tunnel into container `name` until Ctrl-C."""
+    listeners = [(forward.bind, forward.port) for forward in parsed.forwards]
+    program = launch.source(wire, "listen", listeners)
+    command = launch.exec_command(runtime, name, program, interactive=True)
+    try:
+        code, stopped = asyncio.run(host.run_until_signal(command, parsed.forwards))
+    except FileNotFoundError:
+        raise errors.ReadinessError(f"{command[0]} is not on PATH") from None
+    if code and not stopped:
+        raise errors.RuntimeFailure(f"the helper exited with code {code}")

hello_127/errors.py

@@ -0,0 +1,9 @@
+"""The two failures a command can raise. Grammar errors need no class."""
+
+
+class ReadinessError(Exception):
+    """Something the run needed was missing, found before the first write."""
+
+
+class RuntimeFailure(Exception):
+    """A run that stopped partway, after the first write."""

hello_127/host.py

@@ -0,0 +1,67 @@
+"""The Mac side: the relay."""
+
+import asyncio
+import signal
+
+from hello_127 import wire
+
+STOP_GRACE = 5.0
+
+
+async def run(command, forwards, stop=None):
+    """Run the helper command and relay each connection to its forward's target.
+
+    An OPEN frame names its forward by index in `forwards`, and the connection goes to
+    that forward's `host:hostport`.
+
+    The helper runs in its own session, so Ctrl-C reaches only this process. Setting
+    `stop` closes the helper's stdin, which tells it to exit. Return the helper's exit
+    code and whether `stop` ended the run.
+    """
+    stop = stop or asyncio.Event()
+    process = await asyncio.create_subprocess_exec(
+        *command,
+        stdin=asyncio.subprocess.PIPE,
+        stdout=asyncio.subprocess.PIPE,
+        start_new_session=True,
+    )
+    tunnel = wire.Tunnel(process.stdout, process.stdin, {}, {})
+
+    async def dial(payload):
+        """Open a connection to the target of the forward an OPEN frame names."""
+        (index,) = wire.INDEX.unpack(payload)
+        if index >= len(forwards):
+            raise OSError(f"no forward number {index}")
+        return await asyncio.open_connection(forwards[index].host, forwards[index].hostport)
+
+    relay = asyncio.create_task(wire.dispatch(tunnel, dial=dial))
+    stopped = asyncio.create_task(stop.wait())
+    await asyncio.wait({relay, stopped}, return_when=asyncio.FIRST_COMPLETED)
+
+    if stop.is_set():
+        wire.log("outside: stopping, closing the helper's input")
+        process.stdin.close()
+    try:
+        await asyncio.wait_for(process.wait(), STOP_GRACE)
+    except TimeoutError:
+        wire.log(f"outside: helper still running after {STOP_GRACE:g} s, killing exec")
+        process.kill()
+        await process.wait()
+    await relay
+    stopped.cancel()
+    return process.returncode, stop.is_set()
+
+
+async def run_until_signal(command, forwards):
+    """Run the tunnel until SIGINT or SIGTERM, and return what `run` returns."""
+    stop = asyncio.Event()
+    loop = asyncio.get_running_loop()
+    for sig in (signal.SIGINT, signal.SIGTERM):
+        loop.add_signal_handler(sig, stop.set)
+    for forward in forwards:
+        wire.log(
+            f"outside: relaying {forward.bind}:{forward.port}"
+            f" to {forward.host}:{forward.hostport}"
+        )
+    wire.log("outside: Ctrl-C to stop")
+    return await run(command, forwards, stop=stop)

hello_127/launch.py

@@ -0,0 +1,20 @@
+"""The exec commands that run a program from this package inside a container."""
+
+from pathlib import Path
+
+EXEC = {"docker": ["docker", "exec"], "container": ["container", "exec"]}
+
+
+def source(module, entry, *arguments):
+    """Return `module`'s own file, then one call to `entry(*arguments)`, for `python3 -c`."""
+    call = ", ".join(map(repr, arguments))
+    return f"{Path(module.__file__).read_text()}\n{entry}({call})\n"
+
+
+def exec_command(runtime, name, program, interactive=False):
+    """Return the exec command that runs `program` with python3 inside container `name`.
+
+    `interactive` adds `-i`, which keeps the program's stdin connected. The helper
+    needs it for its frames and its stop. Without it, the helper never exits.
+    """
+    return [*EXEC[runtime], *(["-i"] if interactive else []), name, "python3", "-c", program]

hello_127/query.py

@@ -0,0 +1,57 @@
+"""Ask Ollama one question from inside a container, and print the answer as it streams.
+
+Sent into the container as `python3 -c`, like the helper, so it stays standard library
+only and runs on Python 3.10. It dials only the address it is given.
+"""
+
+import http.client
+import json
+import sys
+import urllib.error
+import urllib.request
+
+MODEL = "hf.co/CohereLabs/tiny-aya-global-GGUF:Q4_K_M"
+PROMPT = "Say hello from a container in five sentences."
+
+
+def fail(message):
+    """Print one line to stderr and exit 1."""
+    print(f"hello-127: {message}", file=sys.stderr, flush=True)
+    raise SystemExit(1)
+
+
+def ask(address, port):
+    """Post the prompt to address:port and print the streamed answer.
+
+    The answer counts as finished only at Ollama's `done` line. A stream that ends
+    before it fails, since `http.client` ends quietly when a cut falls between chunks.
+    """
+    url = f"http://{address}:{port}/api/chat"
+    body = json.dumps(
+        {"model": MODEL, "messages": [{"role": "user", "content": PROMPT}]}
+    ).encode()
+    try:
+        reply = urllib.request.urlopen(url, body)
+    except urllib.error.HTTPError as error:
+        fail(f"Ollama answered {error.code}: {json.load(error).get('error', '')}")
+    except urllib.error.URLError as error:
+        if isinstance(error.reason, ConnectionRefusedError):
+            fail(f"nothing answers on {address}:{port} here. Is the tunnel running?")
+        fail(f"cannot reach {address}:{port}: {error.reason}")
+    except http.client.RemoteDisconnected:
+        fail("the tunnel closed the connection. Is Ollama running on the Mac?")
+    with reply:
+        try:
+            for line in reply:
+                part = json.loads(line)
+                if "error" in part:
+                    print()
+                    fail(f"Ollama stopped with an error: {part['error']}")
+                print(part["message"]["content"], end="", flush=True)
+                if part.get("done"):
+                    print()
+                    return
+        except http.client.IncompleteRead:
+            pass
+    print()
+    fail("the answer was cut off before Ollama finished it")

hello_127/wire.py

@@ -0,0 +1,196 @@
+"""Carry TCP connections as frames over a pair of pipes.
+
+Both ends of the tunnel run this file. The Mac side imports it. The container side
+receives its source through `python3 -c`, so it stays standard library only, runs on
+Python 3.10, and never writes to stdout, which is the wire.
+"""
+
+import asyncio
+import errno
+import itertools
+import struct
+import sys
+from collections import namedtuple
+
+OPEN, DATA, CLOSE = 1, 2, 3
+HEADER = struct.Struct("!BII")
+INDEX = struct.Struct("!H")
+CHUNK = 64 * 1024
+
+Tunnel = namedtuple("Tunnel", "pipe_in pipe_out writers remaining")
+"""One end of the tunnel: the pipe both ways, and its open connections.
+
+`writers` maps a connection number to its socket's writer. `remaining` counts the
+directions of that connection still open, from 2 down to 0.
+"""
+
+
+def log(message):
+    """Print one line to stderr, since stdout belongs to the frames."""
+    print(f"hello-127: {message}", file=sys.stderr, flush=True)
+
+
+def frame(kind, conn, payload=b""):
+    """Return one frame: kind, connection number, payload length, then the payload."""
+    return HEADER.pack(kind, conn, len(payload)) + payload
+
+
+async def read_frame(pipe):
+    """Return the next (kind, conn, payload) from the pipe, or None at its end."""
+    try:
+        kind, conn, length = HEADER.unpack(await pipe.readexactly(HEADER.size))
+        payload = await pipe.readexactly(length)
+    except asyncio.IncompleteReadError:
+        return None
+    return kind, conn, payload
+
+
+def open_link(tunnel, conn, writer):
+    """Record a new connection with both of its directions open."""
+    tunnel.writers[conn] = writer
+    tunnel.remaining[conn] = 2
+
+
+def finish_half(tunnel, conn):
+    """Count one direction of a connection as done, and drop it once both are."""
+    if conn not in tunnel.remaining:
+        return
+    tunnel.remaining[conn] -= 1
+    if tunnel.remaining[conn] == 0:
+        del tunnel.remaining[conn]
+        tunnel.writers.pop(conn).close()
+
+
+async def pump(tunnel, conn, reader):
+    """Copy one socket's bytes into DATA frames, then send CLOSE at its end."""
+    try:
+        while True:
+            chunk = await reader.read(CHUNK)
+            if not chunk:
+                break
+            tunnel.pipe_out.write(frame(DATA, conn, chunk))
+            await tunnel.pipe_out.drain()
+    except ConnectionError:
+        pass
+    if not tunnel.pipe_out.is_closing():
+        tunnel.pipe_out.write(frame(CLOSE, conn))
+    finish_half(tunnel, conn)
+
+
+async def deliver(tunnel, conn, payload):
+    """Write a DATA frame's payload to its socket, if the socket is still there."""
+    writer = tunnel.writers.get(conn)
+    if writer is None or writer.is_closing():
+        return
+    writer.write(payload)
+    try:
+        await writer.drain()
+    except ConnectionError:
+        pass
+
+
+def half_close(tunnel, conn):
+    """Act on a CLOSE frame: end the socket's write side and count the direction."""
+    writer = tunnel.writers.get(conn)
+    if writer is None:
+        return
+    try:
+        if writer.can_write_eof():
+            writer.write_eof()
+    except OSError:
+        pass
+    finish_half(tunnel, conn)
+
+
+async def dispatch(tunnel, dial=None):
+    """Act on frames from the pipe until it ends, then close every connection.
+
+    `dial` takes an OPEN frame's payload and opens its far end. Only the Mac side
+    passes one. It runs inline, so no DATA frame overtakes the dial for its own
+    connection.
+    """
+    pumps = set()
+    while True:
+        got = await read_frame(tunnel.pipe_in)
+        if got is None:
+            break
+        kind, conn, payload = got
+        if kind == OPEN and dial is not None:
+            try:
+                reader, writer = await dial(payload)
+            except OSError as error:
+                log(f"connection {conn}: dial failed: {error}")
+                tunnel.pipe_out.write(frame(CLOSE, conn))
+                continue
+            open_link(tunnel, conn, writer)
+            task = asyncio.ensure_future(pump(tunnel, conn, reader))
+            pumps.add(task)
+            task.add_done_callback(pumps.discard)
+        elif kind == DATA:
+            await deliver(tunnel, conn, payload)
+        elif kind == CLOSE:
+            half_close(tunnel, conn)
+    for writer in tunnel.writers.values():
+        writer.close()
+    tunnel.writers.clear()
+    tunnel.remaining.clear()
+    for task in pumps:
+        task.cancel()
+
+
+async def stdio_pipes():
+    """Return this process's stdin and stdout as an asyncio reader and writer."""
+    loop = asyncio.get_running_loop()
+    pipe_in = asyncio.StreamReader()
+    await loop.connect_read_pipe(
+        lambda: asyncio.StreamReaderProtocol(pipe_in), sys.stdin.buffer
+    )
+    transport, protocol = await loop.connect_write_pipe(
+        asyncio.streams.FlowControlMixin, sys.stdout.buffer
+    )
+    pipe_out = asyncio.StreamWriter(transport, protocol, None, loop)
+    return pipe_in, pipe_out
+
+
+async def serve_inside(listeners):
+    """Listen on each (address, port) and send every connection through stdout.
+
+    An OPEN frame carries its listener's index in `listeners`, so the Mac side knows
+    where to dial. A listener that cannot bind ends the helper, with no partial tunnel.
+    """
+    pipe_in, pipe_out = await stdio_pipes()
+    tunnel = Tunnel(pipe_in, pipe_out, {}, {})
+    numbers = itertools.count(1)
+
+    def acceptor(index):
+        """Return the accept callback for the listener at `index`."""
+
+        async def accept(reader, writer):
+            """Number a new connection, announce it with its listener, and pump it."""
+            conn = next(numbers)
+            open_link(tunnel, conn, writer)
+            pipe_out.write(frame(OPEN, conn, INDEX.pack(index)))
+            await pump(tunnel, conn, reader)
+
+        return accept
+
+    servers = []
+    for index, (address, port) in enumerate(listeners):
+        try:
+            servers.append(await asyncio.start_server(acceptor(index), address, port))
+        except OSError as error:
+            reason = error.strerror
+            if error.errno == errno.EADDRINUSE:
+                reason = "already in use in this container"
+            log(f"inside: cannot listen on {address}:{port}: {reason}")
+            raise SystemExit(1) from None
+        log(f"inside: listening on {address}:{port}")
+    await dispatch(tunnel)
+    for server in servers:
+        server.close()
+    log("inside: input ended, helper exiting")
+
+
+def listen(listeners):
+    """Run the inside half until stdin ends. The container's entry point."""
+    asyncio.run(serve_inside(listeners))

hello_127-0.1.1.dist-info/METADATA

@@ -0,0 +1,305 @@
+Metadata-Version: 2.4
+Name: hello-127
+Version: 0.1.1
+Summary: Carry TCP over a container's standard streams to a service on the Mac's loopback
+Author: Go Nakamaru
+Author-email: Go Nakamaru <gonakamaru@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Operating System :: MacOS
+Requires-Python: >=3.14
+Project-URL: Repository, https://github.com/east-van-ai/hello-127
+Project-URL: Changelog, https://github.com/east-van-ai/hello-127/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# hello-127
+
+![CI](https://github.com/east-van-ai/hello-127/actions/workflows/ci.yaml/badge.svg)
+
+Can a Docker or Apple Container with no network access still reach a service on
+the Mac's 127.0.0.1, such as Ollama? Yes, through a pipe: the standard streams
+of `docker exec -i` or `container exec -i`. hello-127 is a small command that
+carries TCP through that pipe.
+
+hello-127 is a reusable CLI tool for this purpose. This page covers its design,
+limitations, install, behaviour, and known failure modes.
+
+## How a container reaches loopback today
+
+A program on a Mac binds to 127.0.0.1 to stay private. Ollama on a Mac does
+this by default. Only programs on the same machine should reach it.
+
+Docker Desktop bends that. When a Docker container connects to the Mac, Docker
+Desktop's own process, `com.docker.backend`, opens a fresh connection to
+127.0.0.1 on the Mac. Ollama sees a local client. The macOS firewall sees an
+outgoing connection, and never asks.
+
+Measured on macOS with Docker Desktop 4.92.0 and Ollama 0.33.3:
+
+- During a run, `lsof` shows `com.docker.backend` as Ollama's only client.
+- A test web server bound to 127.0.0.1 refused the Mac's own LAN address.
+  A container on Docker's default network read from it anyway.
+
+That is a gap. "Bound to loopback" stops meaning "local programs only" the
+moment Docker Desktop is running.
+
+Apple Container has no such hop. Its traffic arrives over a network
+interface, so reaching Ollama there needs a firewall exception or sudo.
+
+## The same job, on purpose
+
+Every container runtime can already run a program inside a container and
+hand you its standard input and output: `docker exec -i`, or
+`container exec -i`. That is a pipe. hello-127 carries TCP through it.
+
+```text
+  container (--network none)                  Mac
+ ┌──────────────────────────────┐         ┌──────────────────────────┐
+ │ your program                 │         │       ┌──────────┐       │
+ │   │ connects to              │         │    ┌─ │ Ollama   │◄─┐    │
+ │   ▼ 127.0.0.1:11434          │  stdin  │    ▼  └──────────┘  │    │
+ │ helper     ◄─────────────────┼─────────┼──  hello-127        │    │
+ │   └─────────────────────────►┼─────────┼──► dials 127.0.0.1 ─┘    │
+ │                              │  stdout │                          │
+ └──────────────────────────────┘         └──────────────────────────┘
+```
+
+- **Inside the container**, a small helper listens on 127.0.0.1:11434. It
+  shares the container's network, so your program sees Ollama as local.
+- **Over the pipe**, each connection becomes frames: open, data, close, each
+  tagged with a connection number. Many connections share one pipe.
+- **On the Mac**, hello-127 reads the frames and dials Ollama on loopback.
+  Every connection goes out, none comes in. No firewall prompt, no sudo.
+
+The helper is not installed in the image. hello-127 sends its source as an
+argument to `python3 -c`, so the image needs only `python3`, 3.10 or newer.
+
+None of this is new. SSH's `ProxyCommand` carries one TCP stream over a
+program's standard streams. `ssh -L` and `kubectl port-forward` carry many
+connections through one channel.
+
+## What it is not
+
+It carries bytes, and never reads them. Whatever the service lets a local
+client do, a program in the container can do too. The tunnel opens the whole
+service, not one part of it.
+
+It also changes how a connection ends. TCP has two endings: a clean close,
+and a reset when something breaks. The pipe has no frame for a reset, so
+every ending arrives as a clean close. A protocol that marks its own end,
+as HTTP does, still notices a cut. A protocol that simply stops at the end
+of the connection cannot tell a crash from a finish.
+
+A gatekeeper is the other design. It understands each request and decides
+what to allow. hello-127 makes the pipe on purpose and leaves the deciding
+out.
+
+## Install
+
+- A Mac.
+- [uv](https://docs.astral.sh/uv/), which installs hello-127 and fetches
+  its Python.
+- [Docker Desktop](https://www.docker.com/products/docker-desktop/), or
+  [Apple Container](https://github.com/apple/container).
+- hello-127, from PyPI:
+
+  ```bash
+  uv tool install hello-127
+  ```
+
+hello-127 itself needs nothing beyond Python's standard library.
+
+## Try it yourself
+
+A container started with `--network none` streams a chat from Ollama
+through hello-127. Without the tunnel, the same chat is refused.
+
+It needs [Ollama](https://ollama.com), running, with Cohere's Tiny Aya
+pulled, a 2.1 GB download:
+
+```bash
+ollama pull hf.co/CohereLabs/tiny-aya-global-GGUF:Q4_K_M
+```
+
+It takes three terminals. In the first, start a container with no network,
+then the tunnel into it:
+
+```bash
+docker run -d --rm --name h127 --network none python:3.12-slim sleep infinity
+hello-127 tunnel docker h127
+```
+
+- `-d` runs the container in the background.
+- `--rm` deletes the container once it stops.
+- `--name h127` gives it the name the other commands use.
+- `--network none` leaves it with loopback only.
+- `sleep infinity` keeps it running with nothing else to do.
+
+```text
+hello-127: outside: relaying 127.0.0.1:11434 to 127.0.0.1:11434
+hello-127: outside: Ctrl-C to stop
+hello-127: inside: listening on 127.0.0.1:11434
+```
+
+In the second, chat from inside the container:
+
+```bash
+hello-127 ollama-query docker h127
+```
+
+```text
+Containerized applications are a revolutionary way to deploy and manage software, ...
+```
+
+`ollama-query` runs a small Python program in the container with
+`docker exec`. It asks Cohere's Tiny Aya one fixed question at
+127.0.0.1:11434 and prints the answer as it streams. It knows nothing else
+about the Mac.
+
+Run it before the tunnel is up, and the same program is refused:
+
+```text
+hello-127: nothing answers on 127.0.0.1:11434 here. Is the tunnel running?
+hello-127: the query exited with code 1
+```
+
+In the third, while the answer streams, ask who holds Ollama's port:
+
+```bash
+lsof -nP -iTCP:11434 -sTCP:ESTABLISHED
+```
+
+- `-n` and `-P` print addresses and ports as numbers, not names.
+- `-iTCP:11434` picks TCP sockets on Ollama's port, 11434.
+- `-sTCP:ESTABLISHED` keeps only live connections, in the ESTABLISHED state.
+
+Once the answer ends, only Ollama's listening socket is left, so the list
+comes back empty.
+
+```text
+COMMAND     PID   USER   FD   TYPE ... NAME
+ollama      803 you       7u  IPv4 ... TCP 127.0.0.1:11434->127.0.0.1:52235 (ESTABLISHED)
+python3.1 55300 you       6u  IPv4 ... TCP 127.0.0.1:52235->127.0.0.1:11434 (ESTABLISHED)
+```
+
+Ollama's only client is hello-127's Python, which `lsof` cuts to
+`python3.1`. It is not `com.docker.backend`.
+
+Back in the first terminal, Ctrl-C closes the helper's input, and the helper
+exits:
+
+```text
+hello-127: outside: stopping, closing the helper's input
+hello-127: inside: input ended, helper exiting
+```
+
+Then `docker stop h127` removes the container.
+
+Apple Container works the same way, with the same flags:
+
+```bash
+container run -d --rm --name h127 --network none python:3.14-slim sleep infinity
+hello-127 tunnel container h127
+```
+
+The chat is `hello-127 ollama-query container h127`, and `lsof` again
+names hello-127's Python. Then `container stop h127` removes the container.
+
+Measured on macOS with Docker 29.8.0, Apple Container 1.6.0, and Ollama
+0.33.3.
+
+## Other ports
+
+Ollama is only the specimen. The tunnel carries any TCP service on the
+Mac's loopback. `--forward` picks both ends, in the shape `ssh -L` uses:
+
+```bash
+hello-127 tunnel docker h127 --forward 127.0.0.2:80:127.0.0.1:11434
+hello-127 ollama-query docker h127 --connect 127.0.0.2:80
+```
+
+- `127.0.0.2:80` is where the helper listens inside. Leave the address out,
+  and it is 127.0.0.1.
+- `127.0.0.1:11434` is what the Mac dials.
+- `--connect` points `ollama-query` at the helper.
+
+`--forward` repeats, and one helper carries every listener:
+
+```bash
+hello-127 tunnel docker h127 --forward 11434:127.0.0.1:11434 --forward 8080:127.0.0.1:8000
+```
+
+Two forwards may dial the same target. Two listeners on the same address
+and port would never both bind, so hello-127 refuses them.
+
+Every address must be loopback, on both ends. A wider address on the Mac
+would make it a relay to the LAN for a container with no network. A wider
+one inside, such as 0.0.0.0, would publish the Mac's service to any
+network the container does have. hello-127 refuses both before anything
+runs:
+
+```text
+usage: hello-127 tunnel RUNTIME CONTAINER [--forward SPEC]...
+hello-127 tunnel: error: argument --forward: not a loopback address: '10.0.0.5'
+```
+
+## How it fails
+
+Each of these was run on both runtimes. The tunnel is left as it is.
+
+- **One slow reader stalls everyone.** All connections share one pipe. A
+  client that leaves about a megabyte unread freezes every other connection.
+  When it reads again, they all finish, and nothing is lost.
+- **A cut-off stream can look complete.** If the tunnel dies mid-stream,
+  the client sees a clean close, not an error. Whether it notices depends on
+  the protocol. Against Ollama, the stock `ollama` library raises an error,
+  and Python's built-in `http.client` does not. So `ollama-query` also
+  waits for Ollama's own `done` line.
+- **A crash on the Mac reads as a finish.** A test server sent 64 KiB, then
+  reset the connection. A client that reads until the end got an error on
+  the Mac itself. Through the tunnel, it got 64 KiB and a clean end: a
+  short file that looks complete. Docker's default network does the same,
+  so `com.docker.backend` hides the reset too.
+- **A service that is down looks like one that hung up.** The helper
+  accepts a connection before the Mac dials. With nothing listening on the
+  Mac, Python's `smtplib` is refused on the Mac and on Docker's default
+  network. Through the tunnel, it connects, then reads "Connection
+  unexpectedly closed". With the server up, its greeting arrives as usual.
+- **No `python3` in the image.** The tunnel stops at once. Apple Container
+  says why. Docker prints its reason on the exec's output, which is the
+  pipe, so hello-127 swallows it and shows only "code 127".
+- **The container is killed mid-stream.** The tunnel notices, reports it,
+  and exits. Nothing is left connected on the Mac.
+- **A Mac address nobody answers on.** Linux answers on all of 127.x, so
+  the helper can listen on 127.0.0.2 inside. macOS answers only on the
+  addresses its loopback carries, by default 127.0.0.1 alone. A forward to
+  127.0.0.2 on the Mac holds each connection for 76 seconds, until macOS
+  gives up. `ollama-query` then blames Ollama: "the tunnel closed the
+  connection".
+- **A dead forward stalls the live ones.** The Mac finishes each dial
+  before it reads the next frame, so no data can overtake its own
+  connection. A dial that hangs holds up every forward. Behind a forward to
+  127.0.0.2, a chat on a healthy forward waited about 75 seconds for its
+  first word, then streamed in full.
+
+And one thing that works: a client that has never heard of hello-127. It
+connects to 127.0.0.1 as usual, and the tunnel does the rest. The stock
+`ollama` Python library, with its default settings, works unchanged from a
+container with no network.
+
+## More documentation
+
+- [Changelog](https://github.com/east-van-ai/hello-127/blob/main/CHANGELOG.md): project history and releases
+
+## Use of AI
+
+Code and documentation are written in collaboration with remote and local AI; design
+decisions, code review, semantic and auditory review, and final judgement stay human.
+
+---
+
+**East Van AI** · AI for the rest of us! · Vancouver, BC, Canada
+
+[github.com/east-van-ai](https://github.com/east-van-ai) · <east-van-ai@proton.me>
+
+Copyright (c) 2026 Go Nakamaru

hello_127-0.1.1.dist-info/RECORD

@@ -0,0 +1,15 @@
+hello_127/__init__.py,sha256=xa3Wg63lu49a6PPA3LyCyLS0inkXzIw0uJE96y995bs,86
+hello_127/args.py,sha256=jvbXpna5u4SCd5HH5dfO02zl1Sn8n4lY1rU7O7plZQc,6823
+hello_127/cli.py,sha256=Fb74YvSv5sxMO7q73jqDMOHpsGgKmux51hFxB582DRA,4685
+hello_127/cli_query.py,sha256=eN5I956WYSJ8dsPJGOCU_XLapAVESZFXZ42b21mxrJc,1591
+hello_127/cli_tunnel.py,sha256=jjrPlY8pj9f6daNcvsSqpzANXPxR61b5OmUKF8tSAxM,2188
+hello_127/errors.py,sha256=PL0QuRDua2rHxGN5dR5nKScD7GRP3kZyiwLWWLslB7o,283
+hello_127/host.py,sha256=6fkx8WadMmWfNIpyqKNmgRmMBW4HLLFsBaM20k5RiX4,2391
+hello_127/launch.py,sha256=tSqDOG_MFWEGo3-0C1eV0KR7UG-kmR5y9cBxvz2Ek9w,845
+hello_127/query.py,sha256=ow0idsh74KYm-lQx4JlPh0BQ2uHX3gFdeG8JH4jsOKs,2134
+hello_127/wire.py,sha256=c1EAYEPTCr2kfkcLfUCq5uyndA_2JYi_1T7iWS37QEQ,6549
+hello_127-0.1.1.dist-info/licenses/LICENSE,sha256=0Ncj7dClY9i2bXd_Bdl2h6o1HTAPKn07GS363J81zbc,1068
+hello_127-0.1.1.dist-info/WHEEL,sha256=si2p8vW03RnhyBnhWl4tj-ObJa78SpE-c9HsEtblGR0,80
+hello_127-0.1.1.dist-info/entry_points.txt,sha256=yLVIzRdUKzPccYIZubT40FdSTIwz1vCwFnhQ5WRhj8M,50
+hello_127-0.1.1.dist-info/METADATA,sha256=U5ePdqnzkW_gfdXjdp19g9haaKahFDGBNCuP4tArReA,12585
+hello_127-0.1.1.dist-info/RECORD,,

hello_127-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.13.5
+Root-Is-Purelib: true
+Tag: py3-none-any

hello_127-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+hello-127 = hello_127.cli:main
+

hello_127-0.1.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Go Nakamaru
+
+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.