gh-chrome 0.1.1__tar.gz

gh_chrome-0.1.1/.github/workflows/cd.yml

@@ -0,0 +1,45 @@
+name: cd
+
+on:
+  push:
+    tags:
+      - v*
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: read
+      packages: write
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: docker/setup-qemu-action@v3
+      - uses: docker/setup-buildx-action@v3
+      - uses: earthly/actions-setup@v1
+        with:
+          version: ^0.8.0
+      - uses: docker/login-action@v3
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      - run: earthly --ci --push +multi --VERSION=${GITHUB_REF_NAME#v}
+
+  pypi:
+    runs-on: ubuntu-latest
+
+    environment: pypi
+
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv build --out-dir dist
+      - run: uv publish

gh_chrome-0.1.1/.github/workflows/chrome.yml

@@ -0,0 +1,30 @@
+name: gh-chrome
+
+on:
+  workflow_dispatch:
+    inputs:
+      session_id:
+        description: gh-chrome session id
+        required: true
+        type: string
+
+jobs:
+  run:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: awalsh128/cache-apt-pkgs-action@latest
+        with:
+          packages: xvfb openbox xdotool x11-utils zstd
+          version: 1.0
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.13"
+
+      - run: pip install gh-chrome
+
+      - run: gh-chrome-runner --session ${{ inputs.session_id }}
+        env:
+          GH_CHROME_URL: ${{ secrets.GH_CHROME_URL }}
+          GH_CHROME_TOKEN: ${{ secrets.GH_CHROME_TOKEN }}
+          GH_CHROME_WORKDIR: ${{ runner.temp }}/gh-chrome

gh_chrome-0.1.1/.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: ci
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:17
+        env:
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: gh_chrome
+        options: >-
+          --health-cmd pg_isready --health-interval 5s
+          --health-timeout 5s --health-retries 10
+        ports:
+          - 5432:5432
+
+    env:
+      DATABASE_URL: postgresql://postgres:postgres@127.0.0.1:5432/gh_chrome
+      GH_CHROME_SKIP_X: "1"
+
+    steps:
+      - uses: actions/checkout@v7
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .

gh_chrome-0.1.1/.gitignore

@@ -0,0 +1,220 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer,
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+# Temporary file for partial code execution
+tempCodeRunnerFile.py
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+temp.nu

gh_chrome-0.1.1/.promptignore

@@ -0,0 +1,2 @@
+*.lock
+**/tests/**

gh_chrome-0.1.1/Earthfile

@@ -0,0 +1,49 @@
+VERSION 0.8
+
+PROJECT wprhvso/gh-browser
+
+ARG --global IMAGE=ghcr.io/wprhvso/gh-chrome
+ARG --global PYTHON=3.13
+
+deps:
+    FROM ghcr.io/astral-sh/uv:python$PYTHON-bookworm-slim
+    ENV UV_COMPILE_BYTECODE=1
+    ENV UV_LINK_MODE=copy
+    ENV UV_PYTHON_DOWNLOADS=never
+    WORKDIR /app
+    COPY pyproject.toml uv.lock ./
+    RUN --mount=type=cache,target=/root/.cache/uv uv sync --frozen --no-dev --no-install-project
+
+build:
+    FROM +deps
+    COPY src src
+    RUN --mount=type=cache,target=/root/.cache/uv uv sync --frozen --no-dev --no-editable
+    SAVE ARTIFACT /app/.venv venv
+
+lint:
+    FROM +deps
+    COPY . .
+    RUN --mount=type=cache,target=/root/.cache/uv uv sync --frozen
+    RUN uv run ruff check .
+    RUN uv run ruff format --check .
+
+docker:
+    FROM python:$PYTHON-slim-bookworm
+    ARG TARGETARCH
+    ARG VERSION=dev
+    ENV PATH=/app/.venv/bin:$PATH
+    ENV PYTHONUNBUFFERED=1
+    ENV GH_CHROME_HOST=0.0.0.0
+    ENV GH_CHROME_STORAGE=/var/lib/gh-chrome
+    WORKDIR /app
+    RUN useradd --system --create-home --uid 10001 gh-chrome && mkdir -p /var/lib/gh-chrome && chown gh-chrome:gh-chrome /var/lib/gh-chrome
+    COPY +build/venv /app/.venv
+    USER gh-chrome
+    VOLUME /var/lib/gh-chrome
+    EXPOSE 8000
+    ENTRYPOINT ["gh-chrome-server"]
+    SAVE IMAGE --push $IMAGE:$VERSION $IMAGE:latest
+
+multi:
+    ARG VERSION=dev
+    BUILD --platform=linux/amd64 --platform=linux/arm64 +docker --VERSION=$VERSION

gh_chrome-0.1.1/PKG-INFO

@@ -0,0 +1,13 @@
+Metadata-Version: 2.4
+Name: gh-chrome
+Version: 0.1.1
+Requires-Python: >=3.13
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx>=0.28
+Requires-Dist: psycopg[binary,pool]>=3.2
+Requires-Dist: pydantic-settings>=2.7
+Requires-Dist: pydantic>=2.10
+Requires-Dist: python-multipart>=0.0.20
+Requires-Dist: python-xlib>=0.33
+Requires-Dist: uvicorn[standard]>=0.34
+Requires-Dist: websockets>=14.1

gh_chrome-0.1.1/README.md

@@ -0,0 +1,91 @@
+# gh-chrome
+
+Chrome, running on a GitHub Actions runner, driven from your machine over HTTPS,
+with the whole session recorded and seekable in a browser.
+
+This is a proof of concept. It exists to show the thing is possible, not to be a
+substitute for a browser you own.
+
+## How it works
+
+```
+your code ──POST──▶ server (VPS) ──SSE──▶ runner (GitHub Actions)
+     ▲                  │  postgres            │  Xvfb + openbox + Chrome
+     └────── SSE ───────┘  segments            │  XTEST input
+                           profiles            └──▶ ffmpeg ──POST──▶ server
+```
+
+Everything is plain HTTPS: server-sent events downstream, POST upstream. No
+websockets anywhere in the protocol.
+
+Calling `new()` returns a session id immediately; the server dispatches the
+workflow in the background and the runner connects back with that id. Commands
+go into a strictly sequential queue and return a handle you await. Input is not
+CDP — the runner moves a real cursor along a WindMouse trajectory and types
+through XTEST, so the page sees trusted events.
+
+## Quick start
+
+```bash
+export GH_CHROME_URL=https://chrome.example.com
+export GH_CHROME_TOKEN=...
+python examples/hello.py
+```
+
+Watch the session at `https://chrome.example.com/s/<id>` (user `admin`, password
+is the token).
+
+## Deploying the server
+
+Set `GH_CHROME_TOKEN`, `GH_CHROME_DATABASE_URL`, `GH_CHROME_STORAGE`,
+`GH_CHROME_PUBLIC_URL`, `GH_CHROME_GITHUB_REPO` and `GH_CHROME_GITHUB_PAT`
+(needs the `actions:write` scope), then run `gh-chrome-server`.
+
+In the repository that runs the workflow, add `GH_CHROME_URL` and
+`GH_CHROME_TOKEN` as secrets.
+
+## Development
+
+```bash
+nix develop
+uv sync
+uv run pytest -q
+```
+
+Tests that need a display are skipped when `Xvfb` is missing or
+`GH_CHROME_SKIP_X` is set. To watch the runner locally:
+
+```bash
+gh-chrome-runner --session <id> --server http://127.0.0.1:8000 &
+x11vnc -display :99 -nopw -forever
+```
+
+## What this cannot do
+
+**Six hours per session.** That is the GitHub job limit. When it expires the
+runner dies, the profile is not saved, and the profile is flagged stale.
+
+**One token, no isolation.** Anyone holding the token can read and control any
+session. There is no per-user separation by design.
+
+**A new IP every time.** Each runner comes up in a random Azure range. Cookies
+survive in the profile archive, but fraud detection keys on the address, so
+Google and banks will re-verify no matter how good the saved state is. Route
+outbound traffic through your own VPS (`GH_CHROME_PROXY`) if you need a session
+to actually hold.
+
+**No state after a crash.** The profile is archived once, at a clean shutdown.
+A killed job loses everything since the session started.
+
+**Latency.** DASH-LL puts the recording one to three seconds behind reality.
+It is a recording you can scrub, not a remote desktop.
+
+## Terms
+
+GitHub Actions is meant for CI. This project runs a browser there, which is
+outside what the Actions terms contemplate — it is a demonstration, and running
+it at scale, or to dodge compute costs, is not something the terms allow.
+
+## License
+
+MIT

gh_chrome-0.1.1/examples/hello.py

@@ -0,0 +1,21 @@
+from __future__ import annotations
+
+import asyncio
+
+import gh_chrome_client
+
+
+async def main() -> None:
+    session = await gh_chrome_client.new(width=1280, height=800, fps=10)
+    print(f"session {session.id}, player at {session.player_url}")
+    async with session as s:
+        await s.ready(timeout=300)
+        await s.goto("https://example.com")
+        print(await s.title())
+        await s.click("a")
+        await s.wait_for_load()
+        print(await s.url())
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

gh_chrome-0.1.1/examples/login_and_persist.py

@@ -0,0 +1,44 @@
+from __future__ import annotations
+
+import asyncio
+import os
+
+import gh_chrome_client
+from gh_chrome_client import Topic
+
+USERNAME = os.environ["DEMO_USERNAME"]
+PASSWORD = os.environ["DEMO_PASSWORD"]
+
+
+async def main() -> None:
+    session = await gh_chrome_client.new(
+        profile="demo",
+        subscribe=[Topic.TABS, Topic.DOWNLOADS],
+        timeout=45.0,
+    )
+    async with session as s:
+        await s.ready(timeout=300)
+        if s.state_stale:
+            print("warning: the previous runner died, the saved state may be outdated")
+
+        await s.goto("https://github.com/login")
+
+        if "login" not in await s.url():
+            print("already signed in, the profile survived")
+            return
+
+        await s.type("#login_field", USERNAME)
+        await s.type("#password", PASSWORD)
+        await s.click('input[name="commit"]')
+
+        try:
+            await s.wait_for_url(r"github\.com/?$", timeout=60)
+        except gh_chrome_client.CommandTimeout:
+            print("two-factor or a captcha is in the way, watch the recording")
+            return
+
+        print("signed in as", await s.text(".AppHeader-user"))
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

gh_chrome-0.1.1/flake.nix

@@ -0,0 +1,48 @@
+{
+  description = "gh-chrome";
+
+  inputs.nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
+
+  outputs = { self, nixpkgs }:
+    let
+      system = "x86_64-linux";
+      pkgs = nixpkgs.legacyPackages.${system};
+      libs = with pkgs; [
+        stdenv.cc.cc.lib
+        zlib
+        xorg.libX11
+        xorg.libXtst
+        xorg.libXi
+        xorg.libXext
+      ];
+    in
+    {
+      devShells.${system}.default = pkgs.mkShell {
+        packages = with pkgs; [
+          python313
+          uv
+          postgresql_17
+          ffmpeg-full
+          xorg.xorgserver
+          xorg.xdpyinfo
+          xdotool
+          openbox
+          x11vnc
+          chromium
+          zstd
+        ];
+
+        env = {
+          LD_LIBRARY_PATH = pkgs.lib.makeLibraryPath libs;
+          UV_PYTHON_DOWNLOADS = "never";
+          GH_CHROME_CHROME_BINARY = "${pkgs.chromium}/bin/chromium";
+        };
+
+        shellHook = ''
+          export PGDATA="$PWD/.pgdata"
+          export PGHOST="$PWD/.pgsock"
+          export DATABASE_URL="postgresql:///gh_chrome?host=$PGHOST"
+        '';
+      };
+    };
+}

gh_chrome-0.1.1/pyproject.toml

@@ -0,0 +1,90 @@
+[project]
+name = "gh-chrome"
+version = "0.1.1"
+requires-python = ">=3.13"
+dependencies = [
+    "fastapi>=0.115",
+    "httpx>=0.28",
+    "psycopg[binary,pool]>=3.2",
+    "pydantic>=2.10",
+    "pydantic-settings>=2.7",
+    "python-multipart>=0.0.20",
+    "python-xlib>=0.33",
+    "uvicorn[standard]>=0.34",
+    "websockets>=14.1",
+]
+
+[project.scripts]
+gh-chrome = "gh_chrome_client.__main__:main"
+gh-chrome-server = "gh_chrome_server.__main__:main"
+gh-chrome-runner = "gh_chrome_runner.__main__:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = [
+    "src/gh_chrome_client",
+    "src/gh_chrome_protocol",
+    "src/gh_chrome_runner",
+    "src/gh_chrome_server",
+]
+
+[dependency-groups]
+dev = ["pytest>=8.3", "pytest-asyncio>=0.25", "ruff>=0.9"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py313"
+
+[tool.ruff.lint]
+select = [
+    "A",
+    "ARG",
+    "ASYNC",
+    "B",
+    "C4",
+    "E",
+    "ERA",
+    "F",
+    "I",
+    "N",
+    "PL",
+    "PTH",
+    "RET",
+    "RUF",
+    "S",
+    "SIM",
+    "UP",
+    "W",
+]
+ignore = ["PLR0913", "S101"]
+
+[tool.ruff.lint.isort]
+known-first-party = [
+    "gh_chrome_client",
+    "gh_chrome_protocol",
+    "gh_chrome_runner",
+    "gh_chrome_server",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+
+[tool.basedpyright]
+pythonVersion = "3.13"
+typeCheckingMode = "strict"
+reportMissingTypeStubs = false
+reportImportCycles = false
+reportAny = false
+reportExplicitAny = false
+reportUnusedCallResult = false
+reportUnannotatedClassAttribute = false
+reportImplicitStringConcatenation = false
+reportPrivateUsage = false
+reportUnknownMemberType = false
+reportUnknownVariableType = false
+reportUnknownArgumentType = false
+executionEnvironments = [{ root = "src", extraPaths = ["src"] }]