Perfect_Python500/Dungeons-Proxy
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

DUNGEONS-33: clean shutdown locks and add optional Telegram 2048

Browse Source 
Co-authored-by: multica-agent <github@multica.ai>
This commit is contained in:
perfect_python500
2026-09-06 09:14:08 +05:00
parent eb135ac6ef
commit 5e7b24cbaf
9 changed files with 240 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

13
README.md
View File

@@ -40,6 +40,14 @@ For a visual preview, development mode may run with both tokens empty. It displa
`/start` and `/access` show **Get access** in a private chat. The bot acknowledges button presses, checks the acting admin's actual Telegram ID, and delivers approved numbers privately. The last processed update offset is persisted.
### Optional 2048 game while waiting
If you added a game to this bot in BotFather, set `TELEGRAM_GAME_SHORT_NAME` to its **short name**, for example `dungeons_2048`. This is the value after `?game=` in BotFather's game link, not a numeric game ID or the full link. To create one, use BotFather's `/newgame` for the same bot whose token is configured above.
After **Get access**, users with a pending request receive a native Telegram game card. Its **Play** button opens [Gabriele Cirulli's 2048](https://github.com/gabrielecirulli/2048) at `https://play2048.co/` inside Telegram. The bot uses [`sendGame` and game callbacks](https://core.telegram.org/bots/api#games); playing does not grant access or change the approval request. Telegram score reporting is not integrated.
Leave `TELEGRAM_GAME_SHORT_NAME` empty to disable games; it is entirely optional. A wrong or unavailable game does not cancel the request or prevent admin approval. Correct the short name and press **Get access** again while the request is pending to retry.
## Discord setup
1. Create an application and bot in the Discord Developer Portal. Put the bot token, application ID, and application's public key into `DISCORD_BOT_TOKEN`, `DISCORD_APPLICATION_ID`, and `DISCORD_PUBLIC_KEY`.
@@ -71,6 +79,7 @@ For a visual preview, development mode may run with both tokens empty. It displa
| `GLOBAL_LOGIN_ATTEMPTS` | Aggregate entry limit per window; 100, including successful entries |
| `TRUST_PROXY` | Trust a single IP in `X-Forwarded-For`; false by default |
| `ADMIN_REQUEST_FIELDS` | Optional details shown to admins: `username,display_name,language_code,guild_id,created_at` |
| `TELEGRAM_GAME_SHORT_NAME` | Optional BotFather game short name for this bot; empty disables the 2048 game card |
Platform, numeric user ID, and request ID always appear in the admin message. Missing optional details show as `—`. Display names and usernames are informational; only configured numeric IDs authorize reviews. These details are collected from the bot interaction, not submitted by the website.
@@ -93,7 +102,7 @@ Compose binds the gateway to host loopback for your TLS edge and stores data in
- Requests, approvals, hashed codes, hashed session tokens, hashed-IP rate limits, and the Telegram offset persist in an atomically replaced, fsynced JSON file with mode `0600`. Plain access numbers exist only during generation and DM delivery; they are not stored or logged.
- This is a small private-alpha **single-process** store, capped at 10,000 retained requests and 10,000 active sessions. It is not a distributed database. Use one instance and a durable local volume; do not use autoscaling, clustered workers, or multiple replicas sharing this file. Expired sessions and old request records are pruned periodically; requests are retained for 30 days beyond their last expiry.
- A `.lock` file prevents simultaneous writers. Normal SIGINT/SIGTERM shutdown releases it. After an abrupt kill or host crash, verify the recorded PID belongs to the stopped gateway before removing the stale lock; never delete a live instance's lock. In Docker, inspect the container state before restarting with a stale lock.
- A `.lock` file prevents simultaneous writers. Ctrl+C (SIGINT), SIGTERM, and startup failures release it. Shutdown allows up to five seconds for pending work; if it stalls, the process exits with status 1 and removes the lock synchronously on exit. Repeated Ctrl+C does not interrupt cleanup. After an uncatchable SIGKILL or host crash, verify the recorded PID belongs to the stopped gateway before removing the stale lock; never delete a live instance's lock. In Docker, inspect the container state before restarting with a stale lock.
- Back up the data file and secret together while the gateway is stopped. Corrupt state fails startup instead of silently discarding access controls. Rotating the secret invalidates existing numbers and browser sessions.
- If a code DM fails, the request stays pending and no code is activated; the admin can press Approve again after the user enables DMs. Undelivered admin notifications can be retried with Get access. Duplicate requests/reviews do not create duplicate approvals. After a crash during delivery, the request returns to pending and the admin should approve it again; an uncertain delivery is never activated automatically.
- While a number remains valid, pressing Get access points the user to their existing DM. Lost numbers cannot be recovered from hashes: revoke that user's access below, then let them request a fresh approval.
@@ -117,6 +126,6 @@ npm run check
npm test
```
The suite covers both bot adapters with mocked provider APIs, administrator authorization, failed DM recovery, duplicate reviews, reusable codes and expiry/renewal, persistent sessions, rate limits, signed Discord interactions, unauthenticated HTTP/WebSocket denial, streaming proxy requests, redirects, cookies, logout, and upstream outages. It requires no external credentials. Live Telegram/Discord delivery still needs an installation with real tokens, configured admins and working DMs.
The suite covers both bot adapters with mocked provider APIs, optional Telegram game cards and Play callbacks, game failure isolation, process shutdown and restart, administrator authorization, failed DM recovery, duplicate reviews, reusable codes and expiry/renewal, persistent sessions, rate limits, signed Discord interactions, unauthenticated HTTP/WebSocket denial, streaming proxy requests, redirects, cookies, logout, and upstream outages. It requires no external credentials. Live Telegram/Discord delivery still needs an installation with real tokens, configured admins and working DMs.
Protocol references: [Telegram Bot API](https://core.telegram.org/bots/api), [Discord interactions](https://docs.discord.com/developers/interactions/receiving-and-responding), [Discord application commands](https://docs.discord.com/developers/interactions/application-commands), [http-proxy-middleware 3.x](https://github.com/chimurai/http-proxy-middleware/tree/v3.0.7).