blip-boop 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- blip_boop-0.1.0/.env.example +7 -0
- blip_boop-0.1.0/ADMINISTRATION.md +124 -0
- blip_boop-0.1.0/CHANGELOG.md +28 -0
- blip_boop-0.1.0/DEPLOYMENT.md +94 -0
- blip_boop-0.1.0/DEVELOPMENT.md +215 -0
- blip_boop-0.1.0/LICENSE +21 -0
- blip_boop-0.1.0/MANIFEST.in +20 -0
- blip_boop-0.1.0/PKG-INFO +94 -0
- blip_boop-0.1.0/PYPI_README.md +78 -0
- blip_boop-0.1.0/README.md +105 -0
- blip_boop-0.1.0/RELEASE.md +123 -0
- blip_boop-0.1.0/blip_boop.egg-info/PKG-INFO +94 -0
- blip_boop-0.1.0/blip_boop.egg-info/SOURCES.txt +26 -0
- blip_boop-0.1.0/blip_boop.egg-info/dependency_links.txt +1 -0
- blip_boop-0.1.0/blip_boop.egg-info/entry_points.txt +2 -0
- blip_boop-0.1.0/blip_boop.egg-info/top_level.txt +6 -0
- blip_boop-0.1.0/blip_boop.py +238 -0
- blip_boop-0.1.0/blip_boop_access.py +86 -0
- blip_boop-0.1.0/blip_boop_admin.py +50 -0
- blip_boop-0.1.0/blip_boop_metadata.py +4 -0
- blip_boop-0.1.0/blip_boop_network.py +199 -0
- blip_boop-0.1.0/blip_boop_server.py +440 -0
- blip_boop-0.1.0/pyproject.toml +30 -0
- blip_boop-0.1.0/render.yaml +30 -0
- blip_boop-0.1.0/setup.cfg +4 -0
- blip_boop-0.1.0/tests/test_beta_access.py +368 -0
- blip_boop-0.1.0/tests/test_blip_boop.py +89 -0
- blip_boop-0.1.0/tests/test_relay.py +284 -0
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
# Copy to .env, fill in the values, then run: source .env
|
|
2
|
+
export BLIP_BOOP_CLIENT_ID="your-github-app-client-id"
|
|
3
|
+
export BLIP_BOOP_APP_SLUG="your-github-app-slug"
|
|
4
|
+
export BLIP_BOOP_WEBHOOK_SECRET="replace-with-a-long-random-secret"
|
|
5
|
+
export BLIP_BOOP_ADMIN_TOKEN="replace-with-another-random-secret-at-least-32-characters"
|
|
6
|
+
export BLIP_BOOP_MAX_USERS="50"
|
|
7
|
+
export BLIP_BOOP_MAX_TERMINALS="1"
|
|
@@ -0,0 +1,124 @@
|
|
|
1
|
+
# Beta administration
|
|
2
|
+
|
|
3
|
+
Invitations grant access to a GitHub account. Seats limit how many admitted
|
|
4
|
+
accounts can be present at the same time. An invitation does not reserve a seat.
|
|
5
|
+
|
|
6
|
+
## Configure the operator credential
|
|
7
|
+
|
|
8
|
+
Set `BLIP_BOOP_ADMIN_TOKEN` to a random secret of at least 32 characters in the
|
|
9
|
+
relay environment and your operator terminal. Use a different value from the
|
|
10
|
+
webhook secret. Terminal participants never receive this credential.
|
|
11
|
+
|
|
12
|
+
For example, generate a value locally and copy it into your private environment
|
|
13
|
+
configuration, not into the repository:
|
|
14
|
+
|
|
15
|
+
```sh
|
|
16
|
+
python3 -c 'import secrets; print(secrets.token_hex(32))'
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The relay refuses to start without an administrator credential. Configuration:
|
|
20
|
+
|
|
21
|
+
| Variable | Default | Purpose |
|
|
22
|
+
| --- | --- | --- |
|
|
23
|
+
| `BLIP_BOOP_ADMIN_TOKEN` | Required | Authenticates operator commands |
|
|
24
|
+
| `BLIP_BOOP_MAX_USERS` | `50` | Maximum simultaneous GitHub accounts |
|
|
25
|
+
| `BLIP_BOOP_MAX_TERMINALS` | `1` | Maximum terminal leases per account |
|
|
26
|
+
|
|
27
|
+
Changing these limits or credentials requires restarting the relay. Run one
|
|
28
|
+
relay process: admission and presence leases are protected by an in-process
|
|
29
|
+
lock, not coordinated across multiple service instances.
|
|
30
|
+
|
|
31
|
+
## Create an invitation
|
|
32
|
+
|
|
33
|
+
From the project directory, load your private operator environment and select
|
|
34
|
+
the relay you administer:
|
|
35
|
+
|
|
36
|
+
```sh
|
|
37
|
+
source .env
|
|
38
|
+
export BLIP_BOOP_SERVER=http://127.0.0.1:8766
|
|
39
|
+
python3 blip_boop.py admin invite create --days 7
|
|
40
|
+
```
|
|
41
|
+
|
|
42
|
+
Use your HTTPS service URL instead for Render. Once the package is installed,
|
|
43
|
+
replace `python3 blip_boop.py` with `blip-boop`. Alternatively, specify the address
|
|
44
|
+
before the administration action:
|
|
45
|
+
|
|
46
|
+
```sh
|
|
47
|
+
blip-boop admin --server https://YOUR-RELAY invite create --days 7
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
The JSON output includes an invitation `id`, a secret `code`, and its expiry.
|
|
51
|
+
Send the code privately to one person. The default lifetime is seven days; the
|
|
52
|
+
maximum is 90 days. Codes are displayed only on creation and cannot be retrieved
|
|
53
|
+
from the server later. Only their hashes are stored.
|
|
54
|
+
|
|
55
|
+
During `blip-boop login`, an unregistered person authorizes GitHub, then enters
|
|
56
|
+
the invitation at a hidden terminal prompt. The invitation is consumed only
|
|
57
|
+
when both admission and session creation succeed. Expired, revoked, or consumed
|
|
58
|
+
codes cannot admit another account. Admitted members can sign in again without
|
|
59
|
+
a fresh invitation; a spare code supplied by an existing member is not consumed.
|
|
60
|
+
|
|
61
|
+
## Manage invitations and members
|
|
62
|
+
|
|
63
|
+
```sh
|
|
64
|
+
blip-boop admin invites
|
|
65
|
+
blip-boop admin invite revoke INVITATION_ID
|
|
66
|
+
blip-boop admin users
|
|
67
|
+
blip-boop admin revoke NUMERIC_GITHUB_USER_ID
|
|
68
|
+
blip-boop admin restore NUMERIC_GITHUB_USER_ID
|
|
69
|
+
blip-boop admin status
|
|
70
|
+
blip-boop admin close
|
|
71
|
+
blip-boop admin open
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
`invites` lists metadata, not secret codes. Revoke an unused invitation by its
|
|
75
|
+
public ID. To remove a member who has already joined, revoke the account using
|
|
76
|
+
the numeric GitHub ID shown by `users`. Revocation removes live presence, deletes
|
|
77
|
+
sessions, and blocks new sign-ins, including attempts with another invitation.
|
|
78
|
+
Restoring access does not restore old session tokens: the member must sign in
|
|
79
|
+
again. Ordinary member tokens cannot call administration endpoints.
|
|
80
|
+
|
|
81
|
+
`close` pauses new registrations without consuming attempted invitation codes.
|
|
82
|
+
Existing admitted members can still sign in and join. `open` resumes admission
|
|
83
|
+
with valid invitations. Both settings survive a server restart.
|
|
84
|
+
|
|
85
|
+
`status` reports admitted accounts, connected accounts, connected terminal leases,
|
|
86
|
+
and configured limits. It does not expose these counts to participants and does
|
|
87
|
+
not measure hosting charges or enforce a global billing cap.
|
|
88
|
+
|
|
89
|
+
## How seats work
|
|
90
|
+
|
|
91
|
+
- The 50-account default applies to accounts present together, not all invited
|
|
92
|
+
members. Each account has one terminal, one pixel, and one seat.
|
|
93
|
+
- Admission is checked atomically before registering a terminal lease. Simultaneous
|
|
94
|
+
arrivals cannot exceed the configured account or terminal limit.
|
|
95
|
+
- Already connected accounts can renew their leases while the space is full.
|
|
96
|
+
A new account sees `space full`; a second terminal sees `terminal limit`.
|
|
97
|
+
- The client retries after 30 seconds without asking the person to authenticate
|
|
98
|
+
or redeem another code. There is no reservation or guaranteed queue order.
|
|
99
|
+
- Quitting sends a best-effort leave request. A stale terminal lease expires
|
|
100
|
+
after 45 seconds and is cleaned up on the next relay request. Closing the
|
|
101
|
+
terminal releases its account's seat; after an abrupt exit, wait for expiry
|
|
102
|
+
before opening another terminal.
|
|
103
|
+
- A terminal permits only one active long-poll at a time. The HTTP server also
|
|
104
|
+
bounds request threads to the configured terminal capacity plus 16 extra
|
|
105
|
+
requests, rejecting excess connections rather than growing without a bound.
|
|
106
|
+
|
|
107
|
+
These controls bound admitted presence and waiting requests. They do not replace
|
|
108
|
+
network-level abuse controls, request-rate limiting, or Render billing controls.
|
|
109
|
+
|
|
110
|
+
## Upgrade from the open prototype
|
|
111
|
+
|
|
112
|
+
The existing SQLite database is extended in place. Colors, pixel identifiers,
|
|
113
|
+
sessions, and webhook deduplication data are preserved. Existing prototype
|
|
114
|
+
accounts are **not automatically admitted**: their sessions cannot bypass the
|
|
115
|
+
invitation check.
|
|
116
|
+
|
|
117
|
+
1. Configure the new administrator token and restart the server.
|
|
118
|
+
2. Create an invitation for yourself using an operator command.
|
|
119
|
+
3. Run `blip-boop login --server URL`, authorize GitHub and redeem that invitation.
|
|
120
|
+
4. Reopen your terminal, then invite other testers.
|
|
121
|
+
|
|
122
|
+
Invitations, consumed-code records, access revocations, and registration state
|
|
123
|
+
survive restarts. Presence and live connection claims do not. Avoid rolling back
|
|
124
|
+
to the old server code: it has no beta admission checks.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
# Changelog
|
|
2
|
+
|
|
3
|
+
All notable changes to this project will be documented in this file.
|
|
4
|
+
|
|
5
|
+
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
|
6
|
+
and this project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
|
7
|
+
|
|
8
|
+
## [Unreleased]
|
|
9
|
+
|
|
10
|
+
## [0.1.0] - 2026-11-17
|
|
11
|
+
|
|
12
|
+
### Added
|
|
13
|
+
|
|
14
|
+
- A terminal space with colored participant pixels and white contribution particles.
|
|
15
|
+
- GitHub App device sign-in and shared signals for pushes, issues, pull requests,
|
|
16
|
+
and reviews.
|
|
17
|
+
- Single-use beta invitations, access administration, and admission limits of
|
|
18
|
+
50 simultaneous accounts and one terminal per account.
|
|
19
|
+
- Persistent colors, relay sessions, invitation records, and webhook deduplication.
|
|
20
|
+
- An MIT license and release packaging for the initial 0.1.0 distribution.
|
|
21
|
+
|
|
22
|
+
### Changed
|
|
23
|
+
|
|
24
|
+
- Use the hosted Render relay by default during sign-in.
|
|
25
|
+
- Send compact contribution and idle messages instead of repeating participant lists.
|
|
26
|
+
|
|
27
|
+
[Unreleased]: https://github.com/loreleimoutiez/blip-boop/compare/v0.1.0...HEAD
|
|
28
|
+
[0.1.0]: https://github.com/loreleimoutiez/blip-boop/releases/tag/v0.1.0
|
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
# First Render deployment
|
|
2
|
+
|
|
3
|
+
This is a deployment configuration for a small test group. It does not turn the
|
|
4
|
+
current relay into a production-ready public service. The request limiting,
|
|
5
|
+
abuse controls and load testing described in RELEASE.md remain necessary
|
|
6
|
+
before broad public access.
|
|
7
|
+
|
|
8
|
+
## Cost controls
|
|
9
|
+
|
|
10
|
+
`render.yaml` requests exactly one small paid Python web service and a 1 GB
|
|
11
|
+
persistent disk in Frankfurt. It does not configure autoscaling, a separate
|
|
12
|
+
database service, a paid workspace upgrade, or automatic deploys on commits.
|
|
13
|
+
|
|
14
|
+
Render documents a spending limit for **build pipeline minutes**, not a global
|
|
15
|
+
cap on all service charges. Outbound bandwidth overages can still be billed.
|
|
16
|
+
Fixed compute and disk sizes are not a guarantee of a fixed total bill.
|
|
17
|
+
|
|
18
|
+
Before creating the service:
|
|
19
|
+
|
|
20
|
+
1. Review the current service and disk prices displayed by Render.
|
|
21
|
+
2. Use a Hobby workspace unless you specifically need a paid workspace plan.
|
|
22
|
+
3. In **Workspace Settings → Build Pipeline → Set spend limit**, set additional
|
|
23
|
+
pipeline spending to zero if offered by the dashboard. Verify the value
|
|
24
|
+
before confirming; it controls builds, not runtime or bandwidth charges.
|
|
25
|
+
4. Leave autoscaling and preview environments disabled and review usage in Billing.
|
|
26
|
+
|
|
27
|
+
If an absolute global spending ceiling is required, resolve that requirement
|
|
28
|
+
with the hosting provider before adding paid resources. Do not treat this
|
|
29
|
+
Blueprint as enforcing that ceiling.
|
|
30
|
+
|
|
31
|
+
References: [Render billing FAQ](https://render.com/docs/faq),
|
|
32
|
+
[build pipeline spending limits](https://render.com/docs/build-pipeline).
|
|
33
|
+
|
|
34
|
+
## Prepare the repository
|
|
35
|
+
|
|
36
|
+
Put the project in a GitHub repository that Render can read. The repository can
|
|
37
|
+
be private. Include `render.yaml`, the Python modules, `pyproject.toml`, and the
|
|
38
|
+
documentation. Local credentials, databases and tunnel binaries are excluded by
|
|
39
|
+
the project's `.gitignore`; review staged files before publishing.
|
|
40
|
+
|
|
41
|
+
The configuration file contains no credentials. Fill in environment variables
|
|
42
|
+
in Render, using the values from your local `.env`:
|
|
43
|
+
|
|
44
|
+
| Variable | Value |
|
|
45
|
+
| --- | --- |
|
|
46
|
+
| `BLIP_BOOP_CLIENT_ID` | The GitHub App Client ID, not its numeric App ID |
|
|
47
|
+
| `BLIP_BOOP_APP_SLUG` | The app's URL slug, currently `blip-boop-echo` |
|
|
48
|
+
| `BLIP_BOOP_WEBHOOK_SECRET` | The same secret entered in GitHub's webhook settings |
|
|
49
|
+
| `BLIP_BOOP_ADMIN_TOKEN` | A separate random secret of at least 32 characters |
|
|
50
|
+
|
|
51
|
+
The Blueprint explicitly sets `BLIP_BOOP_MAX_USERS=50` and
|
|
52
|
+
`BLIP_BOOP_MAX_TERMINALS=1`. [Beta administration](ADMINISTRATION.md) describes
|
|
53
|
+
how to create your own invitation and operate the beta.
|
|
54
|
+
|
|
55
|
+
The downloaded GitHub App private key is not used by the current device-login
|
|
56
|
+
and webhook implementation. Do not upload it to the repository or service.
|
|
57
|
+
|
|
58
|
+
## Create and verify the service
|
|
59
|
+
|
|
60
|
+
1. Create a Render account and connect the GitHub repository.
|
|
61
|
+
2. Select **New → Blueprint**, choose the repository, and review `render.yaml`.
|
|
62
|
+
3. Enter the four credentials/configuration values. Review the requested paid service,
|
|
63
|
+
disk, workspace, and total estimate before confirming resource creation.
|
|
64
|
+
4. Once deployed, visit `https://YOUR-SERVICE.onrender.com/health`. The response
|
|
65
|
+
should be `{"ok": true}`.
|
|
66
|
+
5. In the GitHub App settings, replace the temporary webhook URL with
|
|
67
|
+
`https://YOUR-SERVICE.onrender.com/webhooks/github`. Keep webhook delivery
|
|
68
|
+
active and SSL verification enabled, and verify the four event subscriptions.
|
|
69
|
+
6. Set the same administrator token in your operator terminal, create an invitation
|
|
70
|
+
for yourself, then sign in against the new relay. The first login prompts for
|
|
71
|
+
the code. See [Beta administration](ADMINISTRATION.md).
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
blip-boop login --server https://YOUR-SERVICE.onrender.com
|
|
75
|
+
blip-boop
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
The first deployment uses a new database. Sessions from the local relay do not
|
|
79
|
+
transfer; sign in again. Keep future deploys to one instance because presence
|
|
80
|
+
and transient signals are in memory.
|
|
81
|
+
|
|
82
|
+
Check GitHub's webhook deliveries for a successful response. With the terminal
|
|
83
|
+
connected, create an issue or push to a selected repository and verify a particle
|
|
84
|
+
appears. Repeat with a second account. Deployment and restart interrupt live
|
|
85
|
+
connections temporarily; clients should reconnect automatically.
|
|
86
|
+
|
|
87
|
+
The local tunnel is no longer needed once GitHub and both clients are using the
|
|
88
|
+
new relay. Do not stop it while clients or webhooks still depend on it.
|
|
89
|
+
|
|
90
|
+
## After the small-group test
|
|
91
|
+
|
|
92
|
+
Add the permanent relay URL as the client default, complete the release checks,
|
|
93
|
+
and only then publish the package. See RELEASE.md. Future users should need only
|
|
94
|
+
`pipx install blip-boop`, `blip-boop login`, and `blip-boop`.
|
|
@@ -0,0 +1,215 @@
|
|
|
1
|
+
# Development and self-hosting
|
|
2
|
+
|
|
3
|
+
Technical setup for developers and relay operators. For the project overview,
|
|
4
|
+
see [README.md](README.md).
|
|
5
|
+
|
|
6
|
+
Colored pixels sit quietly at the bottom of the screen. When someone contributes,
|
|
7
|
+
a small white particle rises, drifts, and fades away. No scores, leaderboards,
|
|
8
|
+
or public usernames — just a shared sense that someone else is making something.
|
|
9
|
+
|
|
10
|
+
This development version includes an invite-only terminal client and a
|
|
11
|
+
single-process relay. See [Beta administration](ADMINISTRATION.md) for the
|
|
12
|
+
operator credential, single-use codes, connection limits, and upgrade steps.
|
|
13
|
+
It uses a dedicated GitHub App and signed webhooks instead of the delayed public
|
|
14
|
+
activity feed. You must configure the app and run the relay before signing in.
|
|
15
|
+
The hosted beta address is documented in README.md; the setup below is for
|
|
16
|
+
development and self-hosting.
|
|
17
|
+
|
|
18
|
+
For a first hosted test, see [the Render deployment guide](DEPLOYMENT.md).
|
|
19
|
+
The supplied `render.yaml` defines one paid service and a persistent disk;
|
|
20
|
+
it does not enforce a global spending cap.
|
|
21
|
+
|
|
22
|
+
## Install
|
|
23
|
+
|
|
24
|
+
Requirements: Linux or macOS, Python 3.10+, and a terminal with Unicode and
|
|
25
|
+
24-bit ANSI color support. GitHub CLI is no longer required.
|
|
26
|
+
|
|
27
|
+
From this directory, with [pipx](https://pipx.pypa.io) installed:
|
|
28
|
+
|
|
29
|
+
```sh
|
|
30
|
+
pipx install .
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
For an existing installation, update with `pipx install --force .`.
|
|
34
|
+
For development, use `pipx install --editable .` instead. The package has not
|
|
35
|
+
been published on PyPI.
|
|
36
|
+
|
|
37
|
+
Alternatively:
|
|
38
|
+
|
|
39
|
+
```sh
|
|
40
|
+
python3 -m venv .venv
|
|
41
|
+
.venv/bin/python -m pip install .
|
|
42
|
+
source .venv/bin/activate
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
You can also use `python3 blip_boop.py` instead of `blip-boop` in the commands below.
|
|
46
|
+
|
|
47
|
+
## Set up the GitHub App
|
|
48
|
+
|
|
49
|
+
1. Register a GitHub App in your GitHub developer settings. Choose a name and
|
|
50
|
+
homepage URL, and enable **Device flow** for terminal sign-in. This flow does
|
|
51
|
+
not use an OAuth callback URL, a client secret, or an app private key.
|
|
52
|
+
2. Enable webhooks. Use `https://YOUR-RELAY/webhooks/github` as the webhook URL
|
|
53
|
+
and choose a long random webhook secret. The URL must be reachable by GitHub.
|
|
54
|
+
3. Grant read-only repository permissions for **Contents**, **Issues**, and
|
|
55
|
+
**Pull requests**. Metadata access is included by GitHub.
|
|
56
|
+
4. Subscribe to **Push**, **Issues**, **Pull request**, and **Pull request review**
|
|
57
|
+
events. The app also receives authorization revocation events automatically.
|
|
58
|
+
5. Copy the app's **Client ID** (not the numeric App ID), URL slug, and webhook
|
|
59
|
+
secret into a local `.env` file using `.env.example` as a template. Set a
|
|
60
|
+
separate random `BLIP_BOOP_ADMIN_TOKEN` of at least 32 characters too.
|
|
61
|
+
6. Install the app on the repositories you want to contribute from. For other
|
|
62
|
+
people to use it, allow installation on other accounts when registering it.
|
|
63
|
+
|
|
64
|
+
GitHub integration needs the Client ID, app slug and webhook secret. Beta
|
|
65
|
+
administration additionally requires the separate administrator token. GitHub
|
|
66
|
+
handles which selected repositories deliver events; an organization may need to approve
|
|
67
|
+
installation. Signing in alone does not enable activity from every repository.
|
|
68
|
+
|
|
69
|
+
References: [GitHub App device authorization](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/generating-a-user-access-token-for-a-github-app),
|
|
70
|
+
[webhooks with GitHub Apps](https://docs.github.com/en/apps/creating-github-apps/registering-a-github-app/using-webhooks-with-github-apps).
|
|
71
|
+
|
|
72
|
+
## Start the relay
|
|
73
|
+
|
|
74
|
+
From the directory containing your `.env`:
|
|
75
|
+
|
|
76
|
+
```sh
|
|
77
|
+
source .env
|
|
78
|
+
blip-boop serve --data-dir .relay-data
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
The relay listens on `http://127.0.0.1:8765`. For local GitHub testing, forward
|
|
82
|
+
an HTTPS development tunnel to that port and set the GitHub App webhook URL to
|
|
83
|
+
`https://YOUR-TUNNEL/webhooks/github`.
|
|
84
|
+
|
|
85
|
+
For remote clients, expose the same relay through an HTTPS reverse proxy. HTTP
|
|
86
|
+
is accepted by the client only for localhost. Use the final URL directly, without
|
|
87
|
+
redirects; the client does not forward credentials through redirects. The relay's
|
|
88
|
+
`/health` endpoint reports whether it is running.
|
|
89
|
+
|
|
90
|
+
`--host` and `--port` change the bind address and port. `BLIP_BOOP_CLIENT_ID`,
|
|
91
|
+
`BLIP_BOOP_APP_SLUG`, `BLIP_BOOP_WEBHOOK_SECRET`, and `BLIP_BOOP_ADMIN_TOKEN`
|
|
92
|
+
must be set in the server's environment. Terminal clients do not need those
|
|
93
|
+
variables or the webhook secret.
|
|
94
|
+
|
|
95
|
+
This is a development server, not a production hosting setup. It uses one process,
|
|
96
|
+
SQLite, and in-memory presence. Public deployment still needs request limiting,
|
|
97
|
+
network-level abuse controls, HTTPS termination, and hosting configuration.
|
|
98
|
+
Account and terminal admission limits and bounded request threads are implemented;
|
|
99
|
+
per-client request-rate limiting and load testing remain to be completed.
|
|
100
|
+
Multiple workers cannot share the current in-memory event relay.
|
|
101
|
+
|
|
102
|
+
## Sign in and run
|
|
103
|
+
|
|
104
|
+
Create a single-use invitation with your operator credential first; see
|
|
105
|
+
[Beta administration](ADMINISTRATION.md). Existing prototype accounts must
|
|
106
|
+
redeem an invitation once after upgrading.
|
|
107
|
+
|
|
108
|
+
In another terminal:
|
|
109
|
+
|
|
110
|
+
```sh
|
|
111
|
+
blip-boop login --server http://127.0.0.1:8765
|
|
112
|
+
blip-boop
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
For another computer, use your relay's HTTPS URL in `login --server URL`.
|
|
116
|
+
The URL is saved with the session; ordinary launches do not need it again.
|
|
117
|
+
`BLIP_BOOP_SERVER` can also select a server. Switching servers requires signing in
|
|
118
|
+
again; credentials are never silently sent to a different relay.
|
|
119
|
+
|
|
120
|
+
The login command opens GitHub in your browser and displays a device code.
|
|
121
|
+
After authorization, it opens the app installation page so you can select
|
|
122
|
+
repositories. Authorizing an app and installing it on repositories are separate
|
|
123
|
+
steps; both are needed for contributions to appear.
|
|
124
|
+
|
|
125
|
+
```sh
|
|
126
|
+
blip-boop status
|
|
127
|
+
blip-boop --help
|
|
128
|
+
blip-boop --version
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
`status` checks your saved session against the relay without adding a pixel.
|
|
132
|
+
Application terminal text, source code, and documentation are in English.
|
|
133
|
+
|
|
134
|
+
## The shared scene
|
|
135
|
+
|
|
136
|
+
Each connected person has one colored pixel. There are no simulated users or
|
|
137
|
+
manual particle triggers. Each account can connect one terminal at a time. A small dot identifies your own pixel only on your screen.
|
|
138
|
+
|
|
139
|
+
A particle is emitted for each supported webhook:
|
|
140
|
+
|
|
141
|
+
| Activity | Trigger |
|
|
142
|
+
| --- | --- |
|
|
143
|
+
| Push | One particle per push, excluding branch/tag deletion |
|
|
144
|
+
| Pull request | Opened |
|
|
145
|
+
| Issue | Opened |
|
|
146
|
+
| Review | Submitted |
|
|
147
|
+
|
|
148
|
+
Events are attributed to the GitHub sender. A push represents the person who
|
|
149
|
+
pushed, not necessarily the authors of all included commits. Bot events are
|
|
150
|
+
ignored. Events from connected people are broadcast to everyone in this relay;
|
|
151
|
+
there are no private rooms yet. Only install it on repositories whose activity
|
|
152
|
+
timing you want to share, including private repositories if you select them.
|
|
153
|
+
|
|
154
|
+
Particles match the users' small square shape, start white, and fade over
|
|
155
|
+
18–26 seconds. There are no scores, activity histories, or catch-up animations
|
|
156
|
+
when you first join. GitHub delivery can still be delayed: this is responsive
|
|
157
|
+
webhook delivery, not a hard real-time guarantee. Local, unpushed commits are
|
|
158
|
+
not tracked.
|
|
159
|
+
|
|
160
|
+
The client uses an authenticated long-poll connection: the relay answers as soon
|
|
161
|
+
as presence or a contribution changes, otherwise after about 20 seconds. This
|
|
162
|
+
is not periodic polling of GitHub's public activity feed. The participant list
|
|
163
|
+
is sent on initial connection and when membership or colors change. Contributions
|
|
164
|
+
carry only pixel identifiers; idle responses contain only an event cursor.
|
|
165
|
+
Older clients can still request full snapshots. After reconnecting, the presence
|
|
166
|
+
cursor refreshes the list when needed, including after a server restart.
|
|
167
|
+
Color changes reach
|
|
168
|
+
the server on the next request. Network failures show `offline` and reconnect
|
|
169
|
+
automatically. Abruptly closed terminals disappear within about a minute.
|
|
170
|
+
|
|
171
|
+
## Controls and storage
|
|
172
|
+
|
|
173
|
+
- `c`: change your color and save it for future sessions.
|
|
174
|
+
- `q`, `Esc`, or `Ctrl+C`: quit and restore the terminal.
|
|
175
|
+
|
|
176
|
+
Settings live outside the installation directory:
|
|
177
|
+
|
|
178
|
+
| Platform | Configuration directory |
|
|
179
|
+
| --- | --- |
|
|
180
|
+
| Linux | `~/.config/blip-boop/` |
|
|
181
|
+
| macOS | `~/Library/Application Support/blip-boop/` |
|
|
182
|
+
| Absolute `XDG_CONFIG_HOME` set | `$XDG_CONFIG_HOME/blip-boop/` |
|
|
183
|
+
|
|
184
|
+
`settings.json` stores your color. `session.json` holds the relay URL and a
|
|
185
|
+
blip-boop session token with owner-only file permissions. It does not store your
|
|
186
|
+
GitHub access token. When running from the original source directory, an old
|
|
187
|
+
`.local/settings.json` color is imported if no user settings exist yet.
|
|
188
|
+
|
|
189
|
+
The GitHub access token is used transiently during sign-in: the client sends it
|
|
190
|
+
to the chosen relay, which verifies your identity with GitHub, then discards it.
|
|
191
|
+
Use a relay you trust. Relay sessions expire after 30 days; GitHub App revocation
|
|
192
|
+
invalidates them when its webhook is delivered.
|
|
193
|
+
|
|
194
|
+
The relay stores GitHub numeric user IDs, random pixel identifiers, colors,
|
|
195
|
+
hashed session tokens, and delivery IDs in SQLite. Peers receive only pixel IDs,
|
|
196
|
+
colors, and contribution signals, not GitHub IDs, usernames, repository names,
|
|
197
|
+
commit messages, or raw webhook payloads. This hides usernames in the interface;
|
|
198
|
+
it does not guarantee anonymity from activity timing or repeated colors.
|
|
199
|
+
|
|
200
|
+
Webhook signatures are validated before processing. Redeliveries are deduplicated
|
|
201
|
+
for seven days. Sessions and deduplication survive a server restart; live presence
|
|
202
|
+
and recent signals do not. The transient buffer holds up to 1,000 signals and
|
|
203
|
+
only replays signals from the last 45 seconds during a brief reconnection.
|
|
204
|
+
|
|
205
|
+
## Tests
|
|
206
|
+
|
|
207
|
+
```sh
|
|
208
|
+
python3 -m unittest discover -s tests
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
Tests cover two participants receiving a signed contribution, filtering and
|
|
212
|
+
deduplication, invalid signatures, session revocation, presence expiry, HTTP
|
|
213
|
+
routes, device login, and persistent sessions. GitHub is replaced by a test
|
|
214
|
+
identity provider; real GitHub authorization and delivery still need to be
|
|
215
|
+
verified after registering the app and exposing the webhook URL.
|
blip_boop-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Loreleï
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
include README.md
|
|
2
|
+
include PYPI_README.md
|
|
3
|
+
include LICENSE
|
|
4
|
+
include CHANGELOG.md
|
|
5
|
+
include DEVELOPMENT.md
|
|
6
|
+
include RELEASE.md
|
|
7
|
+
include DEPLOYMENT.md
|
|
8
|
+
include ADMINISTRATION.md
|
|
9
|
+
include render.yaml
|
|
10
|
+
include .env.example
|
|
11
|
+
recursive-include tests *.py
|
|
12
|
+
exclude .env
|
|
13
|
+
global-exclude *.pem *.key *.sqlite3 *.sqlite3-* *.pyc
|
|
14
|
+
prune .local
|
|
15
|
+
prune .relay-data
|
|
16
|
+
prune .venv
|
|
17
|
+
prune .venv-release
|
|
18
|
+
prune build
|
|
19
|
+
prune dist
|
|
20
|
+
prune __pycache__
|
blip_boop-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: blip-boop
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Colored presences and floating particles in your terminal.
|
|
5
|
+
Author: Loreleï
|
|
6
|
+
License-Expression: MIT
|
|
7
|
+
Keywords: terminal,github,ambient,collaboration,pixels
|
|
8
|
+
Classifier: Development Status :: 3 - Alpha
|
|
9
|
+
Classifier: Environment :: Console
|
|
10
|
+
Classifier: Operating System :: POSIX
|
|
11
|
+
Classifier: Programming Language :: Python :: 3
|
|
12
|
+
Requires-Python: >=3.10
|
|
13
|
+
Description-Content-Type: text/markdown
|
|
14
|
+
License-File: LICENSE
|
|
15
|
+
Dynamic: license-file
|
|
16
|
+
|
|
17
|
+
# blip-boop
|
|
18
|
+
|
|
19
|
+
**A little company in your terminal.**
|
|
20
|
+
|
|
21
|
+
Leave it open beside your code. You are a small colored pixel at the bottom of
|
|
22
|
+
an otherwise quiet screen. When you contribute on GitHub, a white particle rises,
|
|
23
|
+
drifts, and fades away. Other connected people share the space as colors.
|
|
24
|
+
|
|
25
|
+
No scores, leaderboards, or public usernames. Just a quiet sign that someone
|
|
26
|
+
else is making something.
|
|
27
|
+
|
|
28
|
+
## Install and join
|
|
29
|
+
|
|
30
|
+
Requires Linux or macOS, Python 3.10+, and a terminal with Unicode and 24-bit
|
|
31
|
+
color support. Install with [pipx](https://pipx.pypa.io):
|
|
32
|
+
|
|
33
|
+
```sh
|
|
34
|
+
pipx install blip-boop
|
|
35
|
+
blip-boop login
|
|
36
|
+
blip-boop
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
The hosted beta is **invite-only**. Get a one-time invitation from the operator
|
|
40
|
+
before your first login. Login opens GitHub in your browser and displays a device
|
|
41
|
+
code, then asks for the invitation in a hidden terminal prompt. The invitation
|
|
42
|
+
is linked to your GitHub account; later logins do not need another code.
|
|
43
|
+
|
|
44
|
+
Authorize the GitHub App, then install it on the repositories you want to
|
|
45
|
+
connect. No server setup or GitHub CLI installation is needed to participate.
|
|
46
|
+
The client uses `https://blip-boop-relay.onrender.com` by default.
|
|
47
|
+
|
|
48
|
+
The beta supports 50 simultaneous accounts and one terminal per account.
|
|
49
|
+
If the space is full, the client retries periodically without consuming another
|
|
50
|
+
invitation. Windows is not currently supported.
|
|
51
|
+
|
|
52
|
+
## What makes a particle?
|
|
53
|
+
|
|
54
|
+
- A push, excluding branch or tag deletion: one particle per push.
|
|
55
|
+
- A pull request opened.
|
|
56
|
+
- An issue opened.
|
|
57
|
+
- A review submitted.
|
|
58
|
+
|
|
59
|
+
Only supported GitHub events from connected participants produce particles.
|
|
60
|
+
Local commits that have not been pushed and bot events are not tracked. GitHub
|
|
61
|
+
webhook delivery may be delayed. Particles fade over 18–26 seconds.
|
|
62
|
+
|
|
63
|
+
## Controls
|
|
64
|
+
|
|
65
|
+
- `c`: change your color and save it for next time.
|
|
66
|
+
- `q`, `Esc`, or `Ctrl+C`: quit.
|
|
67
|
+
- A small dot marks your own pixel.
|
|
68
|
+
|
|
69
|
+
```sh
|
|
70
|
+
blip-boop status
|
|
71
|
+
blip-boop --help
|
|
72
|
+
blip-boop --version
|
|
73
|
+
pipx upgrade blip-boop
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
For another relay, run `blip-boop login --server https://YOUR-RELAY`.
|
|
77
|
+
Settings and your relay session are saved in your user configuration directory.
|
|
78
|
+
|
|
79
|
+
## Privacy
|
|
80
|
+
|
|
81
|
+
Peers receive pixel identifiers, colors, and contribution signals, not GitHub
|
|
82
|
+
usernames, repository names, code, or commit messages. The relay uses your
|
|
83
|
+
GitHub numeric user ID to match events to your pixel. It verifies a GitHub access
|
|
84
|
+
token transiently at sign-in; the token is not saved by blip-boop.
|
|
85
|
+
|
|
86
|
+
Connecting a private repository shares the timing of its supported activity.
|
|
87
|
+
Colors and timing can identify someone, so hidden usernames do not guarantee
|
|
88
|
+
anonymity. All participants on the hosted relay share the same space.
|
|
89
|
+
|
|
90
|
+
## License
|
|
91
|
+
|
|
92
|
+
MIT. The package includes client, relay, and operator command code. Hosted relay
|
|
93
|
+
administration requires a separate secret credential; installing the package
|
|
94
|
+
does not grant administrator access.
|