diff --git a/.env.example b/.env.example new file mode 100644 index 0000000..0cb560b --- /dev/null +++ b/.env.example @@ -0,0 +1,40 @@ +# Django environment +# Use "development" locally. Omit or set a production value in production. +PYTHON_ENV=development + +# Django/API secrets +SECRET_KEY=replace-me +API_KEY=replace-me + +# Used in highscores clean-code decoding +NEW_AES_KEY=0123456789abcdef + +# Discord OAuth (set a dedicated application ID for isolated testing) +DISCORD_CLIENT_ID=825618483957071873 +DISCORD_REDIRECT_URI= +DISCORD_API_REDIRECT_URI= +DISCORD_CLIENT_SECRET=replace-me + +# Email +SMTP_SERVER=smtp.example.com +SMTP_PASSWORD=replace-me + +# Optional Discord webhook for highscores notifications +HIGHSCORES_WEBHOOK_URL= + +# Polar subscriptions +POLAR_SERVER=production +# Optional override for self-hosted/proxy SDK API base URLs. Leave blank for Polar production/sandbox. +POLAR_API_BASE_URL= +POLAR_ACCESS_TOKEN= +POLAR_WEBHOOK_SECRET= +POLAR_CHECKOUT_SUCCESS_URL= +POLAR_CUSTOMER_PORTAL_URL= +POLAR_CASUAL_SERVER_METER_ID= +POLAR_CASUAL_SERVER_EVENT_NAME=casual_server_credits +POLAR_REQUEST_TIMEOUT_SECONDS=10 + +# xRC server orchestrator +ORCHESTRATOR_API_BASE_URL= +ORCHESTRATOR_API_TOKEN= +ORCHESTRATOR_REQUEST_TIMEOUT_SECONDS=10 diff --git a/.github/workflows/django.yml b/.github/workflows/django.yml index 07fdd39..44bd359 100644 --- a/.github/workflows/django.yml +++ b/.github/workflows/django.yml @@ -1,55 +1,97 @@ -name: πŸš€ Deploy Django +name: Deploy Django on: push: branches: [main] jobs: - build-deploy: - name: πŸŽ‰ Build and Deploy + validate: + name: Validate runs-on: ubuntu-latest steps: - - name: 🚚 Get latest code - uses: actions/checkout@v2 + - name: Checkout + uses: actions/checkout@v4 - - name: πŸ”¨ Set up Python 3.12 - uses: actions/setup-python@v2 + - name: Set up Python 3.12 + uses: actions/setup-python@v5 with: - python-version: 3.12 + python-version: "3.12" + cache: pip - - name: πŸ›  Install Dependencies + - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt - - name: β–Ά Run Tests - run: | - python manage.py test + - name: Check for missing migrations + run: python manage.py makemigrations --check --dry-run + env: + SECRET_KEY: ci-secret-key + API_KEY: ci-api-key + NEW_AES_KEY: 0123456789abcdef + DISCORD_CLIENT_SECRET: ci-discord-secret + + - name: Apply migrations on a fresh database + run: python manage.py migrate --noinput + env: + SECRET_KEY: ci-secret-key + API_KEY: ci-api-key + NEW_AES_KEY: 0123456789abcdef + DISCORD_CLIENT_SECRET: ci-discord-secret + + - name: Run Django checks + run: python manage.py check + env: + SECRET_KEY: ci-secret-key + API_KEY: ci-api-key + NEW_AES_KEY: 0123456789abcdef + DISCORD_CLIENT_SECRET: ci-discord-secret + + - name: Run tests + run: pytest env: - SECRET_KEY: ${{ secrets.BASE_KEY }} - SMTP_SERVER: ${{ secrets.SMTP_SERVER }} - SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }} - NEW_AES_KEY: ${{ secrets.NEW_AES_KEY }} - DISCORD_CLIENT_SECRET: ${{ secrets.DISCORD_CLIENT_SECRET }} + SECRET_KEY: ci-secret-key + API_KEY: ci-api-key + NEW_AES_KEY: 0123456789abcdef + DISCORD_CLIENT_SECRET: ci-discord-secret + + build-deploy: + name: Build and Deploy + needs: validate - - name: πŸ“¦ Collect Static Files + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python 3.12 + uses: actions/setup-python@v5 + with: + python-version: "3.12" + cache: pip + + - name: Install dependencies run: | - python manage.py collectstatic --noinput + python -m pip install --upgrade pip + pip install -r requirements.txt + + - name: Collect static files + run: python manage.py collectstatic --noinput env: - SECRET_KEY: ${{ secrets.BASE_KEY }} - SMTP_SERVER: ${{ secrets.SMTP_SERVER }} - SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }} - NEW_AES_KEY: ${{ secrets.NEW_AES_KEY }} - DISCORD_CLIENT_SECRET: ${{ secrets.DISCORD_CLIENT_SECRET }} + SECRET_KEY: ci-secret-key + API_KEY: ci-api-key + NEW_AES_KEY: 0123456789abcdef + DISCORD_CLIENT_SECRET: ci-discord-secret - - name: πŸ”ƒ Restart Server + - name: Restart server run: | mkdir tmp touch tmp/restart.txt - - name: ☁ SFTP Deploy + - name: SFTP deploy uses: easingthemes/ssh-deploy@v2 env: SSH_PRIVATE_KEY: ${{ secrets.SERVER_SSH_KEY }} diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml index 1b5b072..dc79e5a 100644 --- a/.github/workflows/tests.yml +++ b/.github/workflows/tests.yml @@ -9,23 +9,47 @@ jobs: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v2 - - name: πŸ”¨ Set up Python 3.12 - uses: actions/setup-python@v2 + - uses: actions/checkout@v4 + + - name: Set up Python 3.12 + uses: actions/setup-python@v5 with: - python-version: 3.12 + python-version: "3.12" + cache: pip - name: Install dependencies run: | python -m pip install --upgrade pip pip install -r requirements.txt + + - name: Check for missing migrations + run: python manage.py makemigrations --check --dry-run + env: + SECRET_KEY: ci-secret-key + API_KEY: ci-api-key + NEW_AES_KEY: 0123456789abcdef + DISCORD_CLIENT_SECRET: ci-discord-secret + + - name: Apply migrations on a fresh database + run: python manage.py migrate --noinput + env: + SECRET_KEY: ci-secret-key + API_KEY: ci-api-key + NEW_AES_KEY: 0123456789abcdef + DISCORD_CLIENT_SECRET: ci-discord-secret + + - name: Run Django checks + run: python manage.py check + env: + SECRET_KEY: ci-secret-key + API_KEY: ci-api-key + NEW_AES_KEY: 0123456789abcdef + DISCORD_CLIENT_SECRET: ci-discord-secret - - name: β–Ά Run Tests - run: | - pytest + - name: Run tests + run: pytest env: - SECRET_KEY: ${{ secrets.BASE_KEY }} - SMTP_SERVER: ${{ secrets.SMTP_SERVER }} - SMTP_PASSWORD: ${{ secrets.SMTP_PASSWORD }} - NEW_AES_KEY: ${{ secrets.NEW_AES_KEY }} - DISCORD_CLIENT_SECRET: ${{ secrets.DISCORD_CLIENT_SECRET }} + SECRET_KEY: ci-secret-key + API_KEY: ci-api-key + NEW_AES_KEY: 0123456789abcdef + DISCORD_CLIENT_SECRET: ci-discord-secret diff --git a/.gitignore b/.gitignore index c3b2e73..646d662 100644 --- a/.gitignore +++ b/.gitignore @@ -132,7 +132,6 @@ dmypy.json # Database *.sqlite3 -migrations/ .vscode/ .DS_Store diff --git a/SRCweb/log_filters.py b/SRCweb/log_filters.py new file mode 100644 index 0000000..df23f23 --- /dev/null +++ b/SRCweb/log_filters.py @@ -0,0 +1,16 @@ +"""Keep Polar's short-lived portal credential out of application access logs.""" +import logging +import re + + +class RedactCustomerSessionToken(logging.Filter): + def filter(self, record): + message = record.getMessage() + redacted = re.sub( + r'(customer_session_token=)[^&\s\"\x27]+', + r'\1[REDACTED]', message, flags=re.IGNORECASE, + ) + if redacted != message: + record.msg = redacted + record.args = () + return True diff --git a/SRCweb/settings.py b/SRCweb/settings.py index 97d7dbe..a965e04 100644 --- a/SRCweb/settings.py +++ b/SRCweb/settings.py @@ -11,8 +11,10 @@ """ from dotenv import load_dotenv +from django.core.exceptions import ImproperlyConfigured from pathlib import Path import os +from urllib.parse import urlencode load_dotenv() @@ -28,14 +30,40 @@ NEW_AES_KEY = os.getenv("NEW_AES_KEY") or "NEW_AES_KEY" # Discord Client ID (client safe) -DISCORD_CLIENT_ID = "825618483957071873" +DISCORD_CLIENT_ID = os.getenv("DISCORD_CLIENT_ID") or "825618483957071873" # SECURITY WARNING: keep the Discord Client Secret used in production secret! DISCORD_CLIENT_SECRET = os.getenv( "DISCORD_CLIENT_SECRET") or "DISCORD_CLIENT_SECRET" + +def required_non_placeholder_env(name, *, development_default=None): + value = os.getenv(name) or development_default + if os.getenv("PYTHON_ENV") == "development": + return value + if not value or value in {name, "replace-me", "changeme", "CHANGE_ME"}: + raise ImproperlyConfigured(f"{name} must be configured in non-development environments.") + return value + + # SECURITY WARNING: keep the API Key used in production secret! -API_KEY = os.getenv("API_KEY") or "API_KEY" +API_KEY = required_non_placeholder_env("API_KEY", development_default="API_KEY") + +# Polar subscriptions +POLAR_SERVER = os.getenv("POLAR_SERVER") or "production" +POLAR_API_BASE_URL = os.getenv("POLAR_API_BASE_URL") or "" +POLAR_ACCESS_TOKEN = os.getenv("POLAR_ACCESS_TOKEN") or "" +POLAR_WEBHOOK_SECRET = os.getenv("POLAR_WEBHOOK_SECRET") or "" +POLAR_CHECKOUT_SUCCESS_URL = os.getenv("POLAR_CHECKOUT_SUCCESS_URL") or "" +POLAR_CUSTOMER_PORTAL_URL = os.getenv("POLAR_CUSTOMER_PORTAL_URL") or "" +POLAR_CASUAL_SERVER_METER_ID = os.getenv("POLAR_CASUAL_SERVER_METER_ID") or "" +POLAR_CASUAL_SERVER_EVENT_NAME = os.getenv("POLAR_CASUAL_SERVER_EVENT_NAME") or "casual_server_credits" +POLAR_REQUEST_TIMEOUT_SECONDS = float(os.getenv("POLAR_REQUEST_TIMEOUT_SECONDS") or 10) + +# xRC server orchestrator +ORCHESTRATOR_API_BASE_URL = os.getenv("ORCHESTRATOR_API_BASE_URL") or "" +ORCHESTRATOR_API_TOKEN = os.getenv("ORCHESTRATOR_API_TOKEN") or "" +ORCHESTRATOR_REQUEST_TIMEOUT_SECONDS = float(os.getenv("ORCHESTRATOR_REQUEST_TIMEOUT_SECONDS") or 10) # Sends an email to admins when debug = false and a 500 server error occurs ADMINS = [('Webmaster', 'webmaster@secondrobotics.org')] @@ -73,7 +101,8 @@ # 'teamleague', # 'ladder', 'discordoauth2', - 'ranked' + 'ranked', + 'subscriptions', ] REST_FRAMEWORK = { @@ -142,6 +171,7 @@ 'console': { 'class': 'logging.StreamHandler', 'formatter': 'verbose', + 'filters': ['redact_customer_session_token'], }, 'file': { 'class': 'logging.handlers.RotatingFileHandler', @@ -149,12 +179,13 @@ 'maxBytes': 1024 * 1024 * 5, # 5 MB 'backupCount': 5, 'formatter': 'verbose', + 'filters': ['redact_customer_session_token'], }, 'mail_admins': { 'level': 'ERROR', 'class': 'django.utils.log.AdminEmailHandler', 'include_html': True, - 'filters': ['require_debug_false'], + 'filters': ['require_debug_false', 'redact_customer_session_token'], } }, 'loggers': { @@ -180,6 +211,9 @@ }, }, 'filters': { + 'redact_customer_session_token': { + '()': 'SRCweb.log_filters.RedactCustomerSessionToken', + }, 'require_debug_false': { '()': 'django.utils.log.RequireDebugFalse', }, @@ -243,19 +277,31 @@ STATICFILES_DIRS = [BASE_DIR / "static"] DISCORD_REDIRECT_URI = "http://localhost:8000/oauth2/login/redirect" DISCORD_API_REDIRECT_URI = "http://localhost:8000/oauth2/loginapi/redirect" - DISCORD_AUTH_URL = "https://discord.com/api/oauth2/authorize?client_id=825618483957071873&redirect_uri=http%3A%2F%2Flocalhost%3A8000%2Foauth2%2Flogin%2Fredirect&response_type=code&scope=identify%20email" - DISCORD_AUTH_API_URL = "https://discord.com/api/oauth2/authorize?client_id=825618483957071873&redirect_uri=http%3A%2F%2Flocalhost%3A8000%2Foauth2%2Floginapi%2Fredirect&response_type=code&scope=identify%20email" else: # production DEBUG = False ALLOWED_HOSTS = ["secondrobotics.org", "www.secondrobotics.org", "mail.secondrobotics.org"] DISCORD_REDIRECT_URI = "https://secondrobotics.org/oauth2/login/redirect" DISCORD_API_REDIRECT_URI = "https://secondrobotics.org/oauth2/loginapi/redirect" - DISCORD_AUTH_URL = "https://discord.com/api/oauth2/authorize?client_id=825618483957071873&redirect_uri=https%3A%2F%2Fsecondrobotics.org%2Foauth2%2Flogin%2Fredirect&response_type=code&scope=identify%20email" - DISCORD_AUTH_API_URL = "https://discord.com/api/oauth2/authorize?client_id=825618483957071873&redirect_uri=https%3A%2F%2Fsecondrobotics.org%2Foauth2%2Floginapi%2Fredirect&response_type=code&scope=identify%20email" CSRF_COOKIE_SECURE = True SESSION_COOKIE_SECURE = True +# A dedicated test application can share its ID with the test bot. Preserve +# production defaults while allowing isolated OAuth login and redirect URLs. +DISCORD_REDIRECT_URI = os.getenv("DISCORD_REDIRECT_URI") or DISCORD_REDIRECT_URI +DISCORD_API_REDIRECT_URI = os.getenv("DISCORD_API_REDIRECT_URI") or DISCORD_API_REDIRECT_URI + + +def discord_authorization_url(redirect_uri): + return "https://discord.com/api/oauth2/authorize?" + urlencode({ + "client_id": DISCORD_CLIENT_ID, "redirect_uri": redirect_uri, + "response_type": "code", "scope": "identify email", + }) + + +DISCORD_AUTH_URL = discord_authorization_url(DISCORD_REDIRECT_URI) +DISCORD_AUTH_API_URL = discord_authorization_url(DISCORD_API_REDIRECT_URI) + SESSION_COOKIE_AGE = 60 * 60 * 24 * 30 # 30 days MAX_UPLOAD_SIZE = "5242880" diff --git a/SRCweb/urls.py b/SRCweb/urls.py index 31ab48c..bca3fb1 100644 --- a/SRCweb/urls.py +++ b/SRCweb/urls.py @@ -30,6 +30,8 @@ path('oauth2/', include('discordoauth2.urls')), path('ranked/', include('ranked.urls')), path('api/ranked/', include('ranked.api.urls', namespace="api-ranked")), + path('subscriptions/', include('subscriptions.urls')), + path('api/subscriptions/', include('subscriptions.api.urls', namespace="api-subscriptions")), ] if settings.DEBUG: diff --git a/conftest.py b/conftest.py new file mode 100644 index 0000000..a2c0e17 --- /dev/null +++ b/conftest.py @@ -0,0 +1,20 @@ +import os +from pathlib import Path +import tempfile + +import pytest +from django.conf import settings + + +@pytest.fixture(scope='session') +def django_db_modify_db_settings(): + if not os.environ.get('ORCHESTRATOR_REPO'): + yield + return + # Real callbacks use separate HTTP/DB threads. SQLite's shared in-memory + # cache raises SQLITE_LOCKED instead of honoring the busy timeout. Exercise + # the production file-backed locking behavior in an isolated test DB. + with tempfile.TemporaryDirectory(prefix='premium-http-db-') as directory: + settings.DATABASES['default'].setdefault('TEST', {})['NAME'] = str(Path(directory) / 'test.sqlite3') + settings.DATABASES['default'].setdefault('OPTIONS', {})['timeout'] = 20 + yield diff --git a/discordoauth2/migrations/0001_initial.py b/discordoauth2/migrations/0001_initial.py new file mode 100644 index 0000000..11d0b77 --- /dev/null +++ b/discordoauth2/migrations/0001_initial.py @@ -0,0 +1,53 @@ +# Generated by Django 3.2.25 on 2026-05-28 04:36 + +import discordoauth2.managers +import django.contrib.auth.validators +import django.core.validators +from django.db import migrations, models +import django.utils.timezone + + +class Migration(migrations.Migration): + + initial = True + + dependencies = [ + ('auth', '0012_alter_user_first_name_max_length'), + ] + + operations = [ + migrations.CreateModel( + name='User', + fields=[ + ('password', models.CharField(max_length=128, verbose_name='password')), + ('last_login', models.DateTimeField(blank=True, null=True, verbose_name='last login')), + ('is_superuser', models.BooleanField(default=False, help_text='Designates that this user has all permissions without explicitly assigning them.', verbose_name='superuser status')), + ('first_name', models.CharField(blank=True, max_length=150, verbose_name='first name')), + ('last_name', models.CharField(blank=True, max_length=150, verbose_name='last name')), + ('display_name', models.CharField(max_length=25, null=True, validators=[django.contrib.auth.validators.ASCIIUsernameValidator(), django.core.validators.MinLengthValidator(4)], verbose_name='display name')), + ('id', models.BigIntegerField(primary_key=True, serialize=False, verbose_name='user id')), + ('username', models.CharField(max_length=100, verbose_name='username')), + ('discriminator', models.CharField(max_length=4, verbose_name='discriminator')), + ('avatar', models.URLField(verbose_name='avatar')), + ('public_flags', models.IntegerField(verbose_name='public flags')), + ('flags', models.IntegerField(verbose_name='flags')), + ('locale', models.CharField(max_length=100, verbose_name='locale')), + ('mfa_enabled', models.BooleanField(verbose_name='multi-factor authentication enabled')), + ('email', models.EmailField(max_length=254, verbose_name='email address')), + ('verified', models.BooleanField(help_text='Whether the user has verified their email address.', verbose_name='email verified')), + ('date_joined', models.DateTimeField(default=django.utils.timezone.now, verbose_name='date joined')), + ('is_staff', models.BooleanField(default=False, help_text='Designates whether the user can log into this admin site.', verbose_name='staff')), + ('is_active', models.BooleanField(default=True, help_text='Designates whether this user should be treated as active. Unselect this instead of deleting accounts.', verbose_name='active')), + ('groups', models.ManyToManyField(blank=True, help_text='The groups this user belongs to. A user will get all permissions granted to each of their groups.', related_name='user_set', related_query_name='user', to='auth.Group', verbose_name='groups')), + ('user_permissions', models.ManyToManyField(blank=True, help_text='Specific permissions for this user.', related_name='user_set', related_query_name='user', to='auth.Permission', verbose_name='user permissions')), + ], + options={ + 'verbose_name': 'user', + 'verbose_name_plural': 'users', + 'abstract': False, + }, + managers=[ + ('objects', discordoauth2.managers.DiscordUserOAuth2Manager()), + ], + ), + ] diff --git a/discordoauth2/migrations/__init__.py b/discordoauth2/migrations/__init__.py new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/discordoauth2/migrations/__init__.py @@ -0,0 +1 @@ + diff --git a/docs/launch-readiness-2026-10-28.md b/docs/launch-readiness-2026-10-28.md new file mode 100644 index 0000000..3756bee --- /dev/null +++ b/docs/launch-readiness-2026-10-28.md @@ -0,0 +1,192 @@ +# Second Robotics premium hosting: launch readiness + +Assessment date: October 28, 2026. + +**Recommendation: do not launch paid subscriptions yet.** Most of the feature exists, but the three release candidates have not been assembled, several normal user actions fail across service boundaries, and billing/recovery paths still have correctness gaps. The next milestone should be a coordinated private beta with Polar sandbox billing, followed by a public launch after the gates below pass. + +This is a repository, history, PR, and targeted code review. It does not establish what is currently deployed or configured on production hosts. No application code was changed, no stash was applied to your checkouts, no branches were switched, and no deployment or real billing operation was performed. Tests and reproductions used disposable environments and copies where necessary. This report is the only intentional repository addition from this assessment. + +## Where the work actually is + +| Repository | Current local state | Remote/review state | What to recover or integrate | +| --- | --- | --- | --- | +| SecondWebsite | `polar-subscriptions` at `9442fed`, plus local changes | [Draft PR #62](https://github.com/SecondRobotics/SecondWebsite/pull/62), open and reported mergeable when inspected. Its committed head has a successful test check. | Local API-key guard, Polar usage retry state/command, migration `0004`, admin/test/CI changes. Integrate six newer commits from remote `main`. | +| xRCRankedBot | Clean `main` at `66a707c` | Current main includes October game/autocomplete fixes. No open migration PR; the only open PR found was dependency PR #84. | Migration is in **`stash@{0}`**, based on `orchestrator-service` at `d437db3`. Several essential new files are in the stash's untracked-files parent. Recover onto current main carefully. | +| xRCServerOrchestrator | `main` at `aa276a4`, one commit ahead of `origin/main`, plus substantial local changes | GitHub `main` remains `cda4a4e`. No non-Dependabot PR was found. | Push/review the binary-diagnostics commit and integration changes: website callbacks/auth, casual lifecycle/idempotency, games endpoint, restart default, tests. | + +Important recovery identifiers: + +```text +Bot migration stash: 42f72f2f8abb38f21942e2008350a4fdc9239736 +Bot stash untracked tree: 6b30ab4f138d2bb467109eef9dbcb0e459bc6ec4 +Bot migration base branch: d437db311117b3bd6eb906dfcbeb8b7a1ede209b +Website subscription head: 9442fed5efc63b9ca417320fed37a1fcb94e8030 +Website remote main: 0cb4eb66fd82ebd1045a0e55eeefa45b0a4a38d7 +Bot remote main: 66a707ca9ed49e0dbf70bfbe34179d169a9d0dbd +Orchestrator remote main: cda4a4e784fbdac310092648def2bc32c4639639 +``` + +The bot stash includes new `orchestrator_client.py`, `website_client.py`, `cogs/casual.py`, orchestration tests, and CI. It removes the old hangout cog and changes ranked/server flows. Checking out `orchestrator-service` alone does **not** restore the migration. The stash was reviewed by extracting both the tracked snapshot and its untracked-files tree into a temporary directory. + +The website branch is seven feature commits ahead of the common ancestor and lacks six commits now on remote main, including high-score client gates, BioBuzz ranked/high-score changes, and the wheel update. The locally cached `origin/main` is stale; its apparent two-commit divergence understates the current remote divergence. [Current website main](https://github.com/SecondRobotics/SecondWebsite/tree/main). + +## Decisions recovered from earlier chats + +Reviewed the subscription design chat, the orchestrator and bot implementation chats, and the July 7 launch review/follow-up. + +- **Polar is the v1 paid provider**, using its Python SDK and credits/meter system. GitHub Sponsors and native Discord subscriptions are future possibilities, not unfinished v1 requirements. +- **Casual hosting goes through the website**, whether initiated on the site or in Discord. The website owns entitlement checks, reservations, and usage records. The orchestrator owns actual game processes. +- Ranked hosting stays free and launches directly from the bot to the orchestrator. Admin hosting remains staff-controlled. +- Bot/orchestrator calls into the website use the existing shared `API_KEY` in `X-API-KEY`; calls to the orchestrator use bearer tokens with scopes. +- **In-memory orchestrator state is intentional.** You explicitly accepted closing all servers on restart and relaunching them afterward. Persistence is not a prerequisite; reliable shutdown, website cleanup, and Discord recovery are. +- Migration baseline repair is a known deployment task. Legacy migration files were previously inconsistent/untracked; rehearse the existing-database transition rather than blindly applying a fresh-database recipe. +- Sandbox testing was accepted. The premium navbar link was deliberately hidden for initial direct-link production testing. `/subscriptions/` remains accessible. +- Agent handoff docs were not intended to be committed merely because they exist locally. Documentation cleanup is not itself a launch blocker. + +The July follow-up implemented the API-key guard, retryable Polar usage, bot player/OPR compatibility, and the default restart mode. Those changes are present, but largely remain local or stashed. Its prior β€œimplemented” conclusion should not be read as β€œintegrated and launch verified.” + +## What is already implemented + +| Area | Implemented behavior | Qualification | +| --- | --- | --- | +| Plans and entitlements | Database-configured plans, price/product/role IDs, monthly allowance, session/concurrency limits, priority selection, comp/provider-neutral entitlements, Django admin | Polar products/benefits still need matching configuration. Adding a provider choice does not implement that provider's billing integration. | +| Billing integration | SDK checkout, signed webhook validation, subscription upserts, meter balance reads, usage ingestion with stable session external IDs | Existing tests mock Polar. A real sandbox billing lifecycle remains unverified here. | +| Website casual hosting | Subscription page, plan/balance/session display, launch and stop forms, authenticated/service APIs, credit reservations, lifecycle callbacks | Start/stop contracts and recovery need fixes below. The page requires refresh for updated state. | +| Usage resilience | Local ledger, one usage entry per session, rounding, pending/failed/sent fields, retry command, admin visibility | Local changes; pending usage is not currently held against the spendable Polar balance. Ingestion still runs inline; exceptions are contained. | +| Orchestrator | Process launch/stop/restart/kill, port allocation, logs/chat/player/score APIs, moderation scopes, admin UI, metrics/readiness, binary updater, runtime limits, events, website callbacks with retries | Core exists on remote; important website-integration behavior is uncommitted locally. Real binary/host behavior needs a smoke test. | +| Bot migration | Orchestrator and website clients; ranked/admin launch/stop/status/moderation paths; website-proxied casual start/status/stop; inactivity and score events; old hangouts removed | In stash. Unit tests pass, but it predates newer main changes and has stale-cache behavior. | +| Previous display fixes | Accepts orchestrator `playerName`/`ipAddress` and split `redOpr`/`blueOpr` | Present in bot stash and covered by tests. | + +The seeded tiers remain Supporter at $5/month, 360 credits and 120-minute sessions; Host at $12/month, 1,500 credits and 240-minute sessions. These are code defaults, not verification of live Polar pricing. Both default to one concurrent server, and one credit represents a runtime minute with five-minute rounding. + +## Launch blockers and required fixes + +### 1. P1 β€” Discord casual launch is rejected by the orchestrator + +The website constructs `actor.type = "discord_bot"` for a bot-origin launch. The orchestrator only accepts `discord_user`, `website_user`, `service`, and `system`. + +Evidence: [website launch actor](/Users/nick/GitHub/SecondWebsite/subscriptions/services.py:334), [orchestrator actor schema](/Users/nick/GitHub/xRCServerOrchestrator/src/services/launchSchemas.ts:3). + +**Reproduction:** sending the website's bot-origin payload to the actual Fastify route with the fake runner returned HTTP 400 `VALIDATION_FAILED` at `actor.type`. + +**Required:** agree on an accepted actor representation, preserve the initiating Discord identity, and test bot β†’ website β†’ actual orchestrator validation. Current unit mocks accept invalid payloads. + +### 2. P1 β€” Website-proxied stop requests omit a required actor + +Website UI/API callers invoke `request_stop_server_session` without an actor. The website client then sends only `reason`, while the orchestrator stop schema requires `actor`. This affects website stops and casual stops proxied from Discord. + +Evidence: [stop service](/Users/nick/GitHub/SecondWebsite/subscriptions/services.py:574), [outgoing stop payload](/Users/nick/GitHub/SecondWebsite/subscriptions/orchestrator.py:83), [required actor](/Users/nick/GitHub/xRCServerOrchestrator/src/services/launchSchemas.ts:68). + +**Reproduction:** a valid website-style launch returned HTTP 201; stopping that session using the website's payload returned HTTP 400 `VALIDATION_FAILED`, `actor: Required`. + +**Required:** supply the appropriate actor or define a deliberate server-side default. Test both entry points against real request validation. + +### 3. P1 β€” Failed Polar usage becomes spendable again + +For Polar users, `available_credits` subtracts open-session allocations from the remote meter balance, but does not subtract stopped-session usage waiting for successful Polar sync. Once a session stops, its reservation disappears even if ingestion failed. The same risk needs consideration during meter-processing delay after ingestion succeeds. + +Evidence: [available credits](/Users/nick/GitHub/SecondWebsite/subscriptions/services.py:108), [usage sync](/Users/nick/GitHub/SecondWebsite/subscriptions/services.py:410). + +**Reproduction:** a user with a remote balance of 60 consumed 60 minutes; ingestion failed and the ledger correctly recorded 60 failed credits. The website nevertheless reported 60 available credits and authorized another 60-minute session. + +**Required:** reconcile unreflected local usage with Polar balance and active reservations. Retain a hold until usage is safely reflected, without subtracting already-reflected usage twice. Cover outages, retry, delayed meter updates, and concurrent launch requests. + +### 4. P1 β€” Callback ordering can resurrect completed sessions + +The orchestrator sends callbacks independently with retries. A delayed `ready` or `launch_accepted` event can arrive after `stopped`; the website unconditionally sets the session back to running/launching. The launch-response handler also unconditionally writes `launching`, potentially overwriting an earlier ready/terminal callback. Event-ID deduplication does not protect against different events arriving out of order. + +Evidence: [launch response update](/Users/nick/GitHub/SecondWebsite/subscriptions/services.py:340), [callback transitions](/Users/nick/GitHub/SecondWebsite/subscriptions/services.py:490), [independent callback sends](/Users/nick/GitHub/xRCServerOrchestrator/src/services/serverManager.ts:655). + +**Reproduction:** process `stopped`, then an older `ready` with a different event ID. The website ends up `running` while a usage ledger entry already exists. + +**Required:** enforce legal/monotonic lifecycle transitions, terminal-state protection, and freshness/ordering rules. Test delayed delivery and callbacks racing launch/stop responses. + +### 5. P1 β€” Failed Polar webhooks are acknowledged on retry without reprocessing + +`process_polar_webhook` writes an event before processing. On failure it preserves that event as failed. A later delivery with the same ID immediately returns the existing record, and the HTTP view responds successfully. Fixing a missing plan mapping then redelivering does not repair the entitlement. + +Evidence: [webhook deduplication and failure path](/Users/nick/GitHub/SecondWebsite/subscriptions/services.py:611), [HTTP response](/Users/nick/GitHub/SecondWebsite/subscriptions/views.py:108). + +**Reproduction:** deliver a subscription event with an unmapped product, add the product mapping, then redeliver the identical event ID. It remains failed and no entitlement is created. + +**Required:** deduplicate successfully completed events, support safe retry of failed processing, and expose a replay/recovery path. Also test older subscription events arriving after newer entitlement state. + +### 6. P1 β€” Destructive restart recovery is incomplete + +The chosen restart policy is valid, but changing the default to `stop` does not finish recovery: + +- Startup reconciliation sends SIGTERM to matching xRC processes without waiting for exit or escalating if they ignore it. Exceptions are logged, but reconciliation is marked complete in `finally`, so readiness can be reported despite failure. +- The website's stale-session command only selects `running`. Lost stop callbacks can leave `stopping` sessions open indefinitely; lost ready callbacks/launch races can leave `launching` sessions open indefinitely. Those sessions reserve credits and block new launches. +- Running sessions are billed using cleanup time, capped by allocation, rather than a proven actual stop time. After a crash/restart this can overstate runtime. +- Callback retries are finite and in memory. Once a terminal callback exhausts retries, there is no durable delivery/reconciliation path. A cron alone does not solve all the states above. +- The bot's event consumer handles match timer/inactivity/chat events, not server termination/restart events. Existing ranked Discord state is not automatically reconciled when the orchestrator loses its old session IDs. + +Evidence: [startup reconciliation](/Users/nick/GitHub/xRCServerOrchestrator/src/services/serverManager.ts:751), [process termination](/Users/nick/GitHub/xRCServerOrchestrator/src/services/processInspector.ts:50), [website cleanup](/Users/nick/GitHub/SecondWebsite/subscriptions/services.py:592), bot stash `cogs/server.py:552`. + +**Reproduction:** stale `launching` and `stopping` sessions were both ignored by `expire_stale_sessions`. + +**Required:** verify processes have actually exited before accepting fresh work; keep readiness failed on reconciliation failure; reconcile every open website state with a defensible billing cutoff; define ranked Discord cleanup on restart. This can remain a simple destructive-restart design without adding persistent live-session storage. + +### 7. P1 β€” The local billing migration fails the required CI gate + +The model's unnamed `polar_status` index generates `subscriptio_polar_s_d17737_idx`; migration `0004` explicitly creates `subscriptio_polar_s_9533a3_idx`. Django detects a missing migration. + +Evidence: [model index](/Users/nick/GitHub/SecondWebsite/subscriptions/models.py:238), [migration index](/Users/nick/GitHub/SecondWebsite/subscriptions/migrations/0004_usage_polar_sync_state.py:35). + +**Reproduction:** `manage.py makemigrations --check --dry-run` exits 1 on both the old venv and a fresh Python 3.12/Django 5.2.18 environment. Django 5 proposes a `RenameIndex` migration. + +**Required:** align model/migration index names or add the appropriate migration, then pass the gate. This is separate from the already-known production baseline rehearsal. + +### 8. P1 β€” Assemble the release without losing newer games or the dropdown fix + +The recovered bot migration and orchestrator know game codes through `22`. Bot main also supports Override (`23`) and BioBuzz (`24`). The migration still uses fixed `@app_commands.choices` lists, including its new casual command. Blindly restoring old config loses games; adding newer games while retaining fixed choices risks reintroducing the October startup failure. + +Evidence: [orchestrator catalog](/Users/nick/GitHub/xRCServerOrchestrator/src/config/games.ts:3), [current bot catalog](/Users/nick/GitHub/xRCRankedBot/config.py:101), bot stash `cogs/casual.py:83` and its ranked/server decorators. + +**Reproduction:** actual orchestrator route requests for codes `23` and `24` both returned HTTP 400 `Unknown gameCode`. + +**Required:** recover the stash onto current bot main, preserve its autocomplete/tests/CI and game names, give the new casual command compatible selection, update the orchestrator catalog and binary, and integrate current website main. Verify slash-command registration and launching both newer games. Commit and review all three resulting release candidates. + +## Other remaining work + +- **Bot casual status cache:** `_get_active_website_session` returns a cached active record without refreshing it. After automatic expiry or a website stop, `/casual_status` can indefinitely show an old launching/running session. Query the website or use bounded cache freshness. Also review the bot's 180-minute input ceiling against Host's advertised 240-minute sessions. Evidence: bot stash `cogs/casual.py:71–89`. +- **Advertised benefits:** seeded Host copy promises saved presets/faster relaunch, but no preset implementation was found. `discord_role_id` is stored/admin-editable; no role-sync implementation was found in these repositories. Either configure/test Polar's Discord benefit externally, implement missing benefits, or change launch copy. Do not sell promises without a working delivery path. +- **Orchestrator retry test:** one complete check run failed and a rerun passed. The test waits for any two fetches, then asserts two `launch_accepted` fetches; a different callback can satisfy the wait early. Wait for the specific retried event. Evidence: [retry test](/Users/nick/GitHub/xRCServerOrchestrator/test/api.test.ts:408). +- **Deployment configuration:** explicitly configure production bearer tokens/scopes; the orchestrator has a permissive default development token. Configure matching shared keys, correct base/public host URLs, real process mode/binary, paths/permissions, ports/firewall, and exactly one chat-relay owner. `/readyz` alone does not validate billing or callback credentials. +- **Recurring jobs and observability:** install and verify `sync_polar_usage` and corrected stale-session cleanup on the actual host. Alert on failed usage, failed webhooks/callbacks, stale open sessions, and failed startup reconciliation. No live scheduler configuration was verified. +- **Dependencies:** there are open dependency PRs in all three repositories. Triage them in the release dependency review; this assessment did not perform a complete vulnerability audit. Avoid assuming every dependency bump is a required compatible change. + +## Verification performed + +| Check | Result | What it proves / limits | +| --- | --- | --- | +| Website existing pytest suite, old `.venv` | 25 passed | Old local runtime is Python 3.9/Django 3.2; this alone was insufficient. | +| Website existing pytest suite, fresh declared dependencies | **25 passed** on Python 3.12.9/Django 5.2.18 | Fresh test database migrations execute; service tests remain heavily mocked. | +| Django system checks, fresh runtime | Passed | Settings/app checks; no live service validation. | +| Missing-migration check, fresh runtime | **Failed** | Index naming drift described above. | +| Bot recovered stash unit tests | **16 passed** | Includes 14 orchestration/client/command tests and two log-regex tests. Uses existing Python 3.9 venv; not the final merged bot candidate or its CI runtime. | +| Bot current main tests in existing venv | Blocked at import: missing `psutil` | Environment deficiency; does not establish a product regression. Final merged candidate needs a fresh Python 3.10 dependency install and full tests. | +| Orchestrator admin + TypeScript build | Passed | Temporary source copy with installed local dependencies; Node 24 locally versus Node 22 in CI. | +| Orchestrator API suite | 19/20 on first check, **20/20 on rerun** | Retry-test race above. Fake processes, not real xRC. | +| Targeted website reproductions | **Four confirmed**, including on fresh runtime | Failed usage reuse; delayed-ready resurrection; failed-webhook replay; cleanup ignoring launching/stopping. Assertions intentionally check for the observed defects. | +| Actual Fastify route contract probes | **Four failures confirmed** | Invalid Discord actor, missing stop actor, missing Override, missing BioBuzz. No real game process or billing calls. | +| Website PR #62 committed-head CI | Successful `test` check at `9442fed` | Does not cover local retry/guard/migration changes. [CI run](https://github.com/SecondRobotics/SecondWebsite/actions/runs/28843125089). | +| Bot current remote main CI | Successful `test` and `check-lock` checks at `66a707c` | Does not cover the stashed migration or its eventual integration. | +| Orchestrator current remote main CI | **Failed** `build-and-test` at `cda4a4e` | [Existing failed job](https://github.com/SecondRobotics/xRCServerOrchestrator/actions/runs/26490784587/job/78077388472). Retained annotation: long-poll event test expected HTTP 200, received 404 (`test/api.test.ts:230`). Full logs have expired (HTTP 410). The local candidate results above are separate; require fresh CI on the assembled release. | + +The modern Python environment and orchestrator/bot copies were disposable. No production SQLite migration, live checkout, real Polar ingestion, Discord registration, game-client join, or remote restart was exercised. Existing green unit tests do not imply the services work together; the contract probes demonstrate why an integration test is necessary. + +## Recommended completion sequence + +1. **Recover and pin release candidates.** Preserve the bot stash, recover it onto current main, integrate website main, and put orchestrator local changes into reviewable commits. Include untracked implementation files and migration `0004`; exclude unrelated generated static files and temporary handoff docs as appropriate. Record all three SHAs. +2. **Fix the blockers above.** Start with actor contracts and migration drift, then accounting, webhook/callback ordering, and restart/reconciliation. Add targeted regression tests and one actual-schema integration test between website and orchestrator. Resolve catalog/autocomplete drift as part of assembly. +3. **Run the intended CI environments.** Website Python 3.12 with declared dependencies; bot Python 3.10 with its merged tests; orchestrator Node 22 with `npm ci` and `npm run check`. Require clean migration checks. Rehearse the baseline transition on a copy of the current production SQLite database, then verify ordinary migrations and seeded plans. Back up before production migration. +4. **Run a small sandbox acceptance matrix.** Use Polar sandbox products/meter/credits benefits and a test Discord guild. Verify checkout β†’ signed entitlement event β†’ launch from website and Discord β†’ ready β†’ client join β†’ stop β†’ one ledger entry β†’ one reflected Polar charge. Confirm balance subtraction and five-minute rounding. Test no entitlement, exhausted balance, concurrency, max duration, failed launch, and subscription cancellation/end-of-period behavior. +5. **Exercise failure recovery.** Drop/reorder callbacks; make Polar unavailable while stopping; restore it and retry without overspending/double charging. Restart/kill the orchestrator with one casual and one ranked session active: all old processes must die, paid sessions must finalize once, credits/concurrency must recover, Discord match resources must be cleared, and fresh launches must succeed. Test callbacks exhausted while the website is down. +6. **Real xRC/ranked smoke.** Use the actual Linux binary: launch/join a casual session and a ranked match; inspect players, scoped IP visibility, chat relay, scores/OPR, match-end/inactivity workflows, ELO submission, and cleanup. Include Override and BioBuzz after catalog/binary alignment. +7. **Coordinated maintenance cutover.** Treat this as one release. Pause new launches and drain active legacy bot servers before starting an orchestrator configured to terminate existing xRC processes. Deploy/migrate the website, start the verified orchestrator, then switch the bot to the matching release. Enable recurring jobs and monitoring, and run direct-link acceptance with the navbar still hidden. Define rollback before beginning: stop new launches, drain processes, revert matching service versions, retain database backups, and reconcile outstanding billing rather than blindly rolling back schema/data. +8. **Public enablement.** Complete the hidden beta, confirm role benefits and tier copy, verify production Polar configuration and a controlled paid lifecycle, then expose the premium link and announce. Switching out of sandbox needs its own production product/meter/key/benefit verification. + +## Practical readiness summary + +The foundation is substantial: this is integration and reliability completion, not a project that needs to be rebuilt. The most immediate problems are concrete and reproducible. A calendar launch estimate would be premature until the bot stash is integrated and the failure-recovery fixes pass. Call the system ready only when one pinned three-repository release passes the sandbox matrix, real ranked/game smoke, migration rehearsal, and destructive-restart test. diff --git a/docs/premium-acceptance-2026-10-29.md b/docs/premium-acceptance-2026-10-29.md new file mode 100644 index 0000000..266cf46 --- /dev/null +++ b/docs/premium-acceptance-2026-10-29.md @@ -0,0 +1,116 @@ +# Premium acceptance evidence β€” 2026-10-29 + +**Status: core integration proven; remaining launch gates are listed below. Do not merge or deploy yet.** + +No production deployment, merge, production billing change, or main-guild role change was performed. The three coordinated PRs remain unmerged: website #67, bot #85, orchestrator #18. + +## Candidate verification + +| Candidate | Code revision | Verification | +| --- | --- | --- | +| Website | `eb4b78d` | 47 tests pass locally and on the Linux droplet, including real Django/Fastify HTTP contracts, three concurrent SQLite regressions, and the sub-second billing regression; updated candidate CI must also pass | +| Ranked bot | `9927f3e` | 31 tests plus 2 log-parser tests pass on Linux; CI passes | +| Orchestrator | `971a3b1` | 28 tests pass locally and in CI; build and website-contract CI pass; preceding 27-test suite also passed on the droplet | + +Fresh database migrations and Django system checks pass. The staging database contains copied public game/plan configuration and disposable test users; it does not contain production customer records. + +On October 30, a fresh production SQLite snapshot was copied into private local storage for the migration rehearsal only. It was not uploaded to the droplet, committed, or used as the staging customer database. The read-only source was `/home/bottxleg/repositories/SecondWebsite/db.sqlite3` through `ssh namecheap`; SQLite's backup API produced a consistent 142,123,008-byte snapshot and its quick check passed. The release migrated a separate disposable copy successfully, including the existing ranked schema's fake-initial baseline and subscriptions migrations through `0006`. All modeled columns were present, foreign-key violations were zero, and exact data digests/counts matched across all 22 existing application tables. The original snapshot's checksum was unchanged after rehearsal. + +## Live acceptance results + +| Gate | Evidence | +| --- | --- | +| Discord OAuth | Both registered localhost redirects persist. Real login returned successfully and created an authenticated session for the intended Discord account. | +| Bot connectivity | The test bot connects and completes startup in Nick's Test Server. A real 25-second idle event poll completes without timing out. | +| Real game processes | Official xRC v21.2b starts Override (23) and BioBuzz (24), reaches `running` with readiness timestamps, then stops. Old OS processes were verified absent. | +| Sandbox checkout | Browser test-card checkout succeeded and created a real Supporter subscription. Initial custom-price checkout could remain in `confirmed` for several minutes before completing. | +| Entitlement and credits | Real signed subscription events activate the correct plan. The initial grant was 360 credits. | +| Service API launch | A Polar-backed real Override session launched through the bot's website API contract. Concurrent launch was rejected (HTTP 403, existing website contract), stop succeeded, and duplicate stop retained one ledger entry. | +| Website UI | A real BioBuzz session launched and stopped using the browser forms. | +| Actual Discord commands | `/casual_start` with Override autocomplete and 5 minutes created a real session; `/casual_status` reported it running; `/casual_stop` finalized it. | +| Usage billing | Three real subscriber sessions each produced one 5-credit ledger entry. Ingestion succeeded, and Polar consumption/balance matched 15 credits consumed / 345 remaining before lifecycle tests. | +| Aggregation delay | After accepted ingestion but before meter aggregation, Polar still reported 360 while the website held the charge and exposed 355. Once aggregation reached 5 consumed, website and meter both reported 355. | +| Ingestion outage | One real usage entry was synced against an intentionally unreachable Polar URL. It became failed; spendable credits stayed held. Restoring the real sandbox endpoint sent it successfully. Re-sync did not duplicate the ledger charge. | +| Exhaustion | A separate zero-credit fixture account was rejected without a reservation or process being created. Later, the real paid VIP customer had an actual zero Polar meter balance during renewal: launch returned HTTP 403 and the server-session count was unchanged. This proves the tested launch path does not create paid overage at zero balance. | +| Duration cap | A 999-minute request was capped to a five-minute fixture plan. The real server stopped automatically with `max_runtime_elapsed`, and one 5-credit usage entry was recorded. | +| Callback outage/restart | Four callback files persisted while the configured receiver was unreachable. Restoring it and restarting the orchestrator replayed them, finalized one charge, and emptied the outbox. This used the complimentary fixture, not paid Polar usage. | +| Crash recovery | With one real ranked and one real casual process alive, the orchestrator was killed. Restart removed both old game processes; reconciliation finalized the lost casual session once. The test invoked reconciliation with zero staleness grace rather than waiting the normal ten minutes. It did not create a real Discord ranked match or prove its role/channel cleanup. | +| Period-end cancellation | A real sandbox cancellation webhook set the cancellation flag while retaining active access. Renewal was then restored. | +| Upgrade | After changing only the private acceptance products to fixed pricing, a real upgrade selected VIP from the actual product ID despite stale supporter metadata. The website showed 1,500 credits and a 240-minute limit; Polar also reported 1,500. | +| Scheduled downgrade | Polar scheduled a Supporter downgrade for the next period while current website access remained VIP. The test schedule was subsequently cleared. | +| Standalone renewal / no rollover | Fixed-price VIP renewal produced paid `subscription_cycle` order `60cd3321-9a77-4818-890b-1245fc3bcfa2`. After the provider's fifteen-minute order delay, both Polar and the website reported exactly 1,500 credits, consumed units zero, and the new period October 30–November 30. The previous 1,500 credits did not roll over; no webhook failures were present. | +| Failed renewal / recovery | Real decline-after-attachment test card caused order `408a841b-5c25-42b8-af20-a1e96819cf30` to remain pending and subscription to become past due. Signed events denied website access and a real launch (403, no session/usage); Polar removed VIP while retaining guild membership. Restoring the successful card automatically paid the same order, restored active access, exactly 1,500 credits, and the VIP role. A real post-fix 0.637-second ready session then charged five credits once, with matching provider/website balance 1,495 and no duplicate-stop charge. | +| Revocation | Immediate revocation of the newly created test subscription removed access. A launch was rejected with HTTP 403 and created no session. A fresh VIP checkout was initially delayed, then completed. Real Polar VIP access and its 1,500-credit balance are restored. | +| Billing portal entry | `https://sandbox.polar.sh/secondrobotics/portal` was verified as this organization's customer portal sign-in page and configured as the test website's Manage billing destination. Customer portal sign-in and both Discord benefit connections were completed; actual portal UI billing changes remain separate from the API lifecycle checks. | + +## Defects found and fixed during acceptance + +1. **Idle bot polling:** the bot asked for a 25-second server wait with a 15-second HTTP deadline. Event requests now allow the whole wait plus overhead; Python 3.10 asyncio timeouts are translated consistently. Regression includes a delayed real localhost HTTP response. +2. **Webhook SDK aliases:** SDK `model_dump()` returned `TYPE`, so signed events were acknowledged but skipped. Serialization now uses wire aliases (`type`); a regression uses the actual SDK event model. Three stored real subscription events were recovered in the disposable test database. +3. **SQLite callback/response races:** stop-response recording, launch-response recording, and callback ownership lookup could upgrade a retained read lock while another writer was active. Stop uses a guarded SQL update; launch locks the user before reading; callback ownership is resolved before its write transaction. Three concurrent file-backed SQLite regressions pass, along with the complete Linux suite. +4. **Private discovery:** `SERVER_PUBLIC_DISCOVERY=false` forces `Register=Off` even when callers request public registration. This is enabled on the test orchestrator and documented for the initial beta. +5. **Return credential handling:** Polar appends a customer-session credential to the checkout success URL. The website discards it from the URL and redacts it from Django access logs. Reverse-proxy access logs must also avoid recording that parameter at eventual cutover. +6. **Sub-second ready-session billing:** a real server ran ready for 0.983 seconds, but the orchestrator's whole-second runtime was zero, so the website omitted its usage entry. Positive ready/stopped timestamps now apply normal five-minute rounding even when whole-second runtime is zero. Sessions stopped before readiness remain uncharged. Both regressions pass, and a real patched 0.637-second session produced one five-credit entry; provider and website reconciled to 1,495. Duplicate stop created no second charge. + +## Billing evidence and remaining launch prerequisites + +### Billing lifecycle and product configuration + +The original sandbox Supporter/VIP products use **custom/name-your-price** prices. Polar rejects changing a subscription **to** a custom-price product. Fixed-price copies support the tested upgrade and scheduled downgrade. Nick approved **fixed $5/$12 launch pricing**. Configure production products accordingly; do not retain custom-price targets if normal plan switching is promised. Original products were not modified; only the private acceptance products use fixed prices. + +Standalone renewal and no rollover passed: paid recurring order `60cd3321-9a77-4818-890b-1245fc3bcfa2` replenished exactly 1,500 credits after the prior 1,500 expired. Both provider and website agreed. Polar defers recurring order creation for fifteen minutes after the period cutoff, so a temporary zero-credit interval before the paid grant is expected and was observed ([order task](https://github.com/polarsource/polar/blob/main/server/polar/order/tasks.py), [paid-order handling](https://github.com/polarsource/polar/blob/main/server/polar/order/service.py)). The first shortened-cycle test was inconclusive because upgrade invoice `bab5689d-5225-4aff-bc82-2f7342356614` collected both the pending $5 Supporter cycle and the $12 VIP upgrade; it was not used as renewal evidence. The organization's `reset` proration mode is disabled; tests used supported `invoice` behavior without changing organization settings. + +A genuine failed renewal also passed. After selecting Stripe's public sandbox decline-after-attachment card ending `0341`, the period ended at `2026-10-30T15:09:47.809701Z`. Recurring order `408a841b-5c25-42b8-af20-a1e96819cf30` was created at `15:24:48Z`, remained pending, and scheduled its next payment attempt for November 1. Polar marked the subscription `past_due`. Its signed event disabled website access; launch returned HTTP 403 without creating a server session or usage entry. Polar removed the VIP role while retaining guild membership; Supporter remained absent. No application webhook records failed. See [Stripe's test-card behavior](https://docs.stripe.com/testing#declined-payments). + +Restoring successful `4242` method `07587eda-50df-4821-ac3d-bf4d313f3b19` as the default automatically retried **the same order**, which became paid with no next attempt scheduled. The provider and website restored active VIP access and exactly 1,500 credits; the actual Discord VIP role returned. The failure method remains attached but is not the default. No replacement subscription or manual role grant was used. A real post-recovery launch exposed the sub-second rounding defect described above. After the fix, a 0.637-second ready session charged five credits exactly once, including after a duplicate stop; both provider and website reconciled to **1,495 credits**, with no failed webhook records. + +Expired portal authentication initially caused card-setting failures; fresh owner login resolved them. The localhost SSH tunnel also stopped overnight while the official webhook listener remained alive, causing forwarding connection refusals. The tunnel was restored, HTTP readiness returned 200, and a metadata-only update preserving existing metadata delivered fresh signed subscription state. Neither interruption remains an unresolved application webhook failure. + +### Discord benefit and real players + +Discord role acceptance is now complete in the isolated guild: actual VIP grant/removal/regrant and Supporter grant/removal passed. Both private products preserve their credit benefits and use `kick_member=false`. The VIP product is restored to VIP-only role benefits. The original main-guild benefit was not edited. See the Discord test setup guide for exact IDs and evidence. + +Still required with the game client/test players: join/password verification, actual player/chat/score/OPR updates, a complete ranked queue-to-ELO match, inactivity behavior, Discord match resource cleanup, and IP scoping with actual player data. Nick has confirmed two players can participate. The droplet initially blocked game ports; temporary source-restricted rules are now prepared as described below. A real Rebuilt 1v1 preflight reached running, listened on TCP and UDP port 11115 with public discovery off, and stopped. This is not a completed Discord ranked match or a real-client reachability test. + +The fresh production snapshot includes Override/BioBuzz ranked modes missing from the older public catalog copied into staging. Only its 53 public game-mode records were copied to the isolated test database; no production user data was uploaded. With no active server sessions, only the test bot was restarted. Discord REST confirmed registered standard choices for BioBuzz 1v1/2v2, Override 1v1/2v2, and Rebuilt 1v1/2v2/3v3. + +### Production prerequisites + +- Fresh production-backup migration rehearsal **passed October 30** as recorded above. Take another consistent backup immediately before the eventual authorized cutover. +- Namecheap currently runs Python 3.9.23/Django 3.2.25. Python 3.12 is installed at `/opt/alt/python312/bin/python3.12`; the application's live Python selection/virtual environment must be moved to 3.12 at the separately authorized cutover. It has not been changed. The candidate requires Django 5.x and CI uses Python 3.12. +- Production currently has no subscriptions tables. The rehearsal seeds the default Host plan; the approved fixed $5/$12 Supporter/VIP plans, allowances, and production Polar mappings still need explicit configuration before exposing premium. Local/staging plan customization is not production configuration. +- Verify the production host can run the official binary and sustain planned concurrency. The current test host required private newer libc and temporary swap. +- Configure production product/meter/benefit IDs, webhook secret, portal URL, service tokens, and recurring workers separately. Sandbox IDs must not be reused in production. +- Review all three PRs together and obtain separate merge/cutover authorization. Website main pushes trigger automatic deployment. + +## Isolated test environment and preservation + +- SSH alias: `digitalocean`. +- Root: `/home/nick/.local/share/second-robotics-test/`; release directory: `releases/20261029/`. +- Website listens on `127.0.0.1:8000`; localhost-only SSH forwarding exposes it at `http://localhost:8000/`. +- Orchestrator listens on `127.0.0.1:3300`. Existing unrelated services on port 3000 were left intact. +- Guild: `663201408581107712`; bot application: `724063847958184046`. +- Runtimes: Python 3.12.16 / Python 3.10.22 / Node 22.23.4. +- The droplet is Ubuntu 20.04, glibc 2.31. Official xRC requires newer libc symbols. Ubuntu Jammy libc6 2.35-0ubuntu3.15 was verified using the signed archive index and SHA256 hashes and extracted privately. Only the test binary's interpreter/RPATH were changed; its original is preserved as `xRC Simulator.x86_64.original`. System libc was not replaced. +- Temporary root-owned mode-600 512 MiB swap file: `acceptance.swap`; it is not configured across reboot. Test startup timeout is 120 seconds. These accommodations do not establish production capacity. +- Private service configuration remains mode 600. Logs, callback outbox, and score archives must be preserved across test restarts. Pending callback files contain connection credentials. +- Official Polar CLI is authenticated to sandbox **SecondRobotics**, not the separate **SecondRoboticsSandbox** organization. It forwards signed events to the private website through the SSH tunnel. Private local artifacts/forwarder logs are under `/private/tmp/second-e2e-prep/`. +- The interrupted turn closed the original SSH tunnel; it was restored as a separate process. Forwarding and the CLI listener must remain running for future events. +- An older sandbox VIP subscription under the original email was left intact. Only the disposable Django profile email was changed to a unique acceptance alias to avoid that pre-existing customer conflict. Do not delete the older subscription as cleanup for this run. + +| Tier | Private acceptance product | +| --- | --- | +| Supporter | `4a900d30-03fb-45cb-a0c4-9053f964d966` | +| VIP Supporter | `794d2bb8-5f3b-4868-975a-fb7c181d8a70` | + +The copied catalog's stale saved-presets promise was cleaned using the existing migration. The acceptance products initially used credits only; their intended Discord benefits have since been configured and verified as described above. Preserve customized launch prices/allowances when applying the actual migration. + +## Current state and next gates + +- The real Polar VIP subscription `8889315a-38ce-40ee-aa7b-b7c2cd09cde2` passed renewal, actual failed renewal, and payment recovery. The successful `4242` card is restored as default; website and provider report active VIP and **1,495 credits** after one verified five-credit post-fix session. The temporary complimentary fallback remains deactivated. +- Isolated Discord role acceptance is complete: VIP grant/removal/regrant and Supporter grant/removal were verified directly in Discord. VIP and guild membership were retained during final Supporter removal. Both private products have their intended final benefits, and the temporary extra Supporter benefit was removed from VIP. [Exact configuration and evidence](premium-discord-test-setup.md). +- No production/main-guild resources were changed, and all coordinated PRs remain unmerged. +- Follow the [ordered remaining live-test sequence](premium-live-test-sequence.md), including exact test queue/channel and evidence requirements. Temporary UFW rules now allow TCP/UDP ports 11115–11117 only from the current SSH client address; a private cleanup record is stored at `acceptance-firewall.json` under the test root. A second player on another network requires a separate source rule. +- Sandbox billing gates are passed: checkout, usage/debit, outages/retry, upgrade/downgrade, cancellation/revocation, standalone renewal/no rollover, zero-balance rejection, actual failed renewal, role revocation, and payment/access/role recovery. A separate production billing configuration and controlled production lifecycle remain cutover prerequisites. +- Next owner participation: confirm the second player's account and readiness for a real test game/full ranked match. Both players share the current network, and its address matches the prepared source-restricted game rules. The fresh production backup has been supplied through SSH and rehearsed successfully. +- Production fixed $5/$12 product configuration, credentials, capacity validation, recurring workers, coordinated review, and separate cutover authorization remain required before launch. diff --git a/docs/premium-discord-test-setup.md b/docs/premium-discord-test-setup.md new file mode 100644 index 0000000..7adbd32 --- /dev/null +++ b/docs/premium-discord-test-setup.md @@ -0,0 +1,39 @@ +# Isolated Polar Discord benefit acceptance + +**Status: complete.** Merchant authorization and both customer connections are complete. Real role changes were verified through Discord's member API, not inferred from Polar statuses or manually assigned. + +## Final configuration + +- Polar organization: SecondRobotics **sandbox**, `c8c9219f-b5eb-42cb-9c75-2d4445de23ad`. +- Test guild: Nick's Test Server, `663201408581107712`. +- Test customer Discord account: `261976608519225345`. +- Polar Sandbox bot: `1285600567409901569`. +- Polar managed role: `1565531587368722462`, positioned above both premium roles. +- Both premium roles have permission bitfield `0`; both benefits use `kick_member=false`. + +| Tier | Role ID | Benefit ID | Private sandbox product | +| --- | --- | --- | --- | +| Supporter | `1565530199838294038` | `d1e7f83d-a107-41d1-ab09-5b7a050a1f2e` | `4a900d30-03fb-45cb-a0c4-9053f964d966` | +| VIP Supporter | `1565530201893380126` | `1bfbd1df-3201-4ed0-868f-992dd9ed4295` | `794d2bb8-5f3b-4868-975a-fb7c181d8a70` | + +Each product retains its original meter-credit benefit. The VIP product's final benefits are exactly `e16f5f1e-b7fe-4e6b-ade7-e56c338de4cd` (credits) and `1bfbd1df-3201-4ed0-868f-992dd9ed4295` (VIP role). Its temporary Supporter benefit has been removed. + +## Verified behavior + +1. Customer connected VIP in the sandbox portal; Polar granted the actual VIP Discord role. +2. Removing the VIP benefit from the private product removed the actual role, without removing guild membership. +3. Reattaching the VIP benefit restored the actual role. +4. The Supporter benefit separately required customer Discord connection. It was temporarily exposed on the private VIP purchase for this test. +5. After connection, Polar granted the actual Supporter role while VIP remained. +6. Removing only that temporary benefit removed Supporter and retained VIP. The final account has VIP only. +7. The website and Polar both retained 1,500 credits throughout the final role cleanup. + +The active restored VIP subscription is `8889315a-38ce-40ee-aa7b-b7c2cd09cde2`. VIP grant: `c9c0cebc-e752-4c90-8d27-d9086a899d64`; Supporter test grant: `704f5e83-76c9-452a-8558-12d57c9cf8b9`. + +The old benefit `887e581d-f3ca-490c-9a84-cff33751d53b` targets main guild `637407041048281098` and was not edited. No original product, main-guild role, production billing resource, merge, or deployment was changed. + +## Repeating the setup + +The CLI creates benefits and attaches them to products. The initial server connection requires Discord authorization through the [sandbox benefits page](https://sandbox.polar.sh/dashboard/secondrobotics/products/benefits). Customer connections are completed separately for each benefit in the [sandbox portal](https://sandbox.polar.sh/secondrobotics/portal), using the checkout email alias containing `+premium-acceptance-20261029`. + +Official setup guide: https://polar.sh/docs/features/benefits/discord-access diff --git a/docs/premium-live-test-sequence.md b/docs/premium-live-test-sequence.md new file mode 100644 index 0000000..e9c36fa --- /dev/null +++ b/docs/premium-live-test-sequence.md @@ -0,0 +1,42 @@ +# Remaining live acceptance sequence + +Use the isolated 20261029 release on `ssh digitalocean`, test guild +`663201408581107712`, and bot `724063847958184046`. No production deployment +or merge is authorized. Completed evidence remains in +[the acceptance report](premium-acceptance-2026-10-29.md). + +| Order | Operator action | Required evidence | +| --- | --- | --- | +| 1 β€” passed | Agent scheduled a short fixed-price sandbox billing period and observed provider orders, credits, signed webhooks, and website entitlement. | Paid `subscription_cycle` order `60cd3321-9a77-4818-890b-1245fc3bcfa2`; exactly 1,500 credits after the fifteen-minute billing delay, without rollover; website and provider agree. | +| 2 β€” passed | A real sandbox decline card caused a failed renewal; restoring the successful default card automatically retried the same order. | Past due denied launches without creating sessions/usage, removed VIP without removing guild membership, then recovered active access, exactly 1,500 credits, and the VIP role. A real post-fix 0.637-second session charged five credits once; provider and website ended at 1,495. | +| 3 | Owner confirms player networks and Discord accounts. Agent opens only the required test game access, checks profiles in the disposable database, and starts a casual server. | Both real clients reach the advertised address. Wrong password fails; correct password succeeds. Public discovery remains off. | +| 4 | Players join opposing alliances, send an identifiable test chat message, and play a scored game. Agent inspects API/events/logs and stops the server. | Player presence, chat, score and OPR agree with the clients; scopes protect actual player IP data; stop closes the process and debits once. | +| 5 | Both players use `/queuestandard`, selecting **Rebuilt 1v1**, in [the test queue channel](https://discord.com/channels/663201408581107712/1565227916432900126). | Bot creates private match resources, supplies a working server/password, and assigns the correct players. No production account creation or leaderboard writes. | +| 6 | Players play and submit actual red/blue scores with `/submit` in the match channel; continue until the bot reports the series complete. | Staging match rows and ELO history match submitted scores; channels/roles and game process are cleaned up after the series. Respect the command's two-minute cooldown. | +| 7 | Agent coordinates a fresh test match for idle timeout, then a separate restart/network-disruption check. Players follow the requested join/leave steps. | Idle/restart cleanup removes stale Discord resources and game processes; a transient network failure does not erase a live match; a new match can start afterward. | +| 8 β€” passed | Agent used the supplied `ssh namecheap` alias to take a consistent read-only SQLite snapshot and migrate a disposable local copy on October 30. | All modeled columns present; zero foreign-key violations; existing data preserved exactly across 22 application tables; original snapshot unchanged. Production was not migrated. | +| 9 | Agent reconciles evidence, fixes findings, runs relevant checks, and updates the three draft PRs. | Every required gate has recorded evidence or a specific unresolved blocker. Merge and production cutover remain a separate owner decision. | + +## Inputs still needed + +- Both players are confirmed on the current network, which matches the prepared + game firewall rules. Confirm when they are ready with xRC v21.2 and Discord. +- The second player's Discord ID if they are not the existing `easierthanpai` + test-guild member. Any profile seeded for ranked acceptance is a test fixture; + it does not count as an additional OAuth login test. +- Production SSH access and the fresh-backup rehearsal are complete. The live + application's Python 3.9 β†’ 3.12 switch remains a cutover prerequisite; it has + not been performed. +- Polar billing acceptance is complete. The successful `4242` card is restored + as default, the subscription is active, and both balances are 1,495 after the + verified five-credit usage debit. Keep credentials and codes out of chat. + +Temporary UFW rules now permit game TCP/UDP ports 11115–11117 from the current +SSH client address only, in addition to the existing SSH and Nginx rules. The +private `acceptance-firewall.json` cleanup record is under the test root. A second +player on a different network needs a separate source rule. A real Rebuilt 1v1 +preflight reached running on port 11115, listened on both TCP and UDP, kept public +discovery off, and accepted a stop request. Actual client reachability remains to +be tested. +Use the current matching xRC client revision; the installed test server is v21.2b. +Connection ports and passwords come from the actual session, not this document. diff --git a/docs/premium-release-checklist.md b/docs/premium-release-checklist.md new file mode 100644 index 0000000..8b1c964 --- /dev/null +++ b/docs/premium-release-checklist.md @@ -0,0 +1,120 @@ +# Premium hosting release checklist + +Current acceptance evidence: [2026-10-29 test run](premium-acceptance-2026-10-29.md). + +This is a coordinated website, ranked-bot, and orchestrator release. Nothing in this preparation authorizes merging or deployment. Keep the premium navbar link hidden for the initial beta. + +## Prepared in code + +- Recovered the bot migration without dropping the original stash; retained Override/BioBuzz and searchable game selection. +- Aligned actual casual launch/stop contracts. Added a local HTTP integration test with real Django and Fastify routes, both launch origins, callbacks, and the two newer games. +- Protected terminal states and launch/stop response races, made failed Polar webhooks replayable, and rejected stale entitlement updates. +- Recorded billing periods on reservations, serialized reservation decisions per user (including SQLite), and kept uncertain launch outcomes reserved until reconciliation. +- Moved Polar ingestion to the scheduled worker. A durable local hold protects credits during ingestion failures and meter aggregation delay. Portal credit grants still affect available balance. +- Added conservative reconciliation for every open session state. Network failure does not prove a process stopped. A reachable orchestrator with a missing session finalizes only last-confirmed runtime. +- Added a file-backed callback outbox that survives restart, process-exit verification/escalation, failed-start cleanup, and bot cleanup of lost ranked sessions. +- Preserved previous score files in archives before port reuse. Scoped event/IP and raw-log reads. Removed the unimplemented saved-presets promise from default Host copy. + +## Actions needed from Nick, in order + +### 1. Finish the existing Polar sandbox configuration + +The October 29–30 acceptance run proves checkout, initial credits, real usage ingestion/debit, outage holds, upgrades with fixed prices, cancellation, revocation, restored access after a fresh checkout, both Discord role lifecycles, standalone renewal without rollover, and actual failed-renewal/payment recovery. Actual zero-provider-balance and past-due launches are denied without creating sessions. The recovered subscription and VIP role returned, and a real sub-second ready session verified the fixed five-credit minimum charge. Fixed $5/$12 pricing is approved; configure production products that way (Polar rejects upgrades to custom-price targets). See the linked evidence report before repeating completed sandbox setup. + +Local configuration already specifies `POLAR_SERVER=sandbox`, an access token, and a meter ID. Do not paste secrets into chat. Add missing values to the appropriate local/private configuration or secret store: + +1. Configure the sandbox webhook endpoint `/subscriptions/polar/webhook/` on a reachable **test** website URL and save its signing secret as `POLAR_WEBHOOK_SECRET`. A local test receiver needs a tunnel or test host; do not point sandbox events at the live production database. +2. Ensure the token can create checkouts, read customer meters, and ingest usage events. Keep all products, meter IDs, and credentials in the same sandbox organization. +3. Verify each active Django `SubscriptionPlan.polar_product_id` against its sandbox product in Django admin. The local database already has mapped **Supporter** (`supporter`, 360 credits, 120-minute max) and **VIP Supporter** (`vip-supporter`, 1,500 credits, 240-minute max) plans. Preserve those customized tiers; do not replace them with the fresh-database Host seed. Configure recurring credits to match the actual advertised plan; one credit is one runtime minute. Configure billing-cycle expiry/no rollover and no paid overage. Verify these behaviors in sandbox rather than assuming defaults. +4. Use a **dedicated meter** for this application's `casual_server_credits` events with a sum of `metadata.credits`. Do not publish unrelated usage to it or manually inject consumption into it. The reconciliation hold uses this dedicated meter's `consumed_units`; it allows credit grants in the portal and does not release holds merely because ingestion was accepted. [Polar customer meter fields](https://polar.sh/docs/api-reference/customer-meters/get). +5. Configure and test Polar's Discord role benefit for each product, or remove the corresponding role promise from the editable plan copy. The website's role ID field does not itself grant Discord roles. Saved presets are deferred and no longer advertised by the default Host plan. +6. Configure `POLAR_CUSTOMER_PORTAL_URL` and test the manage-billing flow. + +### 2. Provide an isolated Linux/Discord acceptance environment + +Use a disposable Linux machine or a test host, a current xRC Linux binary supporting Override/BioBuzz, and a test Discord guild/bot identity. Do not start this orchestrator alongside live unmanaged xRC servers: the intended startup policy terminates existing xRC processes visible to its account. Isolation by host or OS account is necessary for a safe test. + +Set up private configuration, without committing secrets: + +| Direction | Configuration | +| --- | --- | +| Bot + orchestrator β†’ website | Matching strong `API_KEY`; header `X-API-KEY` | +| Website β†’ orchestrator | `ORCHESTRATOR_API_BASE_URL`, `ORCHESTRATOR_API_TOKEN`; token scopes `servers:casual:create,servers:read,servers:stop` | +| Bot β†’ orchestrator | `ORCHESTRATOR_BASE_URL`, `ORCHESTRATOR_TOKEN`; scopes `servers:ranked:create,servers:read,servers:stop` | +| Bot privileged operations | Separate moderation/admin tokens; raw logs require `logs:read` and `moderation:read`; admin operations need their corresponding admin/create/stop/restart scopes | +| Orchestrator β†’ website | `SECONDWEBSITE_BASE_URL` pointing at the same test website/database | +| Client connections | `SERVICE_PUBLIC_HOST`, reachable server port pool and required game traffic allowed by the test host firewall | + +The local website is currently missing its orchestrator URL/token. Production mode also requires explicit non-development service tokens, a non-placeholder shared key, real process mode, and stop-on-restart reconciliation. + +Set orchestrator `SERVER_PUBLIC_DISCOVERY=false` for acceptance and the initial beta; this forces public game-browser registration off for all launch sources. + +Choose one chat-relay owner: orchestrator webhook **or** bot event relay. Preserve runtime log/score directories and `EVENT_LOG_DIR/website-callbacks` across service restarts. Pending callbacks include connection passwords: protect the directory and its backups. No database for live orchestrator state is needed. Periodically review archived score directories and retain/remove them according to your chosen retention policy. + +### 3. Run the sandbox acceptance gate before approving merges + +Once the environment is ready, the candidates must demonstrate: + +1. Sandbox checkout activates the correct entitlement/credits. Role benefit works and manage billing opens. Test downgrade, cancellation through period end, renewal/reset, and past-due/revoked access. +2. Website launch and Discord `/casual_start` both produce a ready real server. Join from a game client. Confirm connection/password, players, chat, and scores. Include Override and BioBuzz. +3. Stop from both entry points. Verify exactly one usage record and one Polar event per session, five-minute rounding, and eventual matching meter debit. Test max duration, exhausted balance, and concurrent launch rejection. +4. Make Polar temporarily unavailable while stopping. Confirm local finalization succeeds, credits remain held, and `sync_polar_usage` later recovers without reusing or charging the same credits twice. +5. Stop the test website long enough to exhaust immediate callback retries, restore it, and confirm the outbox replays. Restart the orchestrator with one ranked and one casual session: old processes must exit, casual usage finalizes once, Discord match resources clear, and fresh launches succeed. A mere network outage must not clear a live ranked match. +6. Complete a real ranked match: queue, roles/channels, free server launch, score/OPR display, ELO submission, inactivity behavior, and cleanup. Verify IPs are absent from ordinary event/player reads and available only to authorized moderation callers. + +The automated checks cover the service contracts and mocked failure cases. They cannot prove Discord registration, a real game-client join, or live Polar benefit/meter configuration. + +### 4. Rehearse against a fresh production database backup + +**Passed October 30:** a fresh consistent snapshot from `ssh namecheap`, `/home/bottxleg/repositories/SecondWebsite/db.sqlite3`, migrated successfully on a disposable local copy. All modeled columns were present, foreign-key violations were zero, and existing data matched exactly across 22 application tables. Production was opened read-only and was not migrated. The private snapshot remains outside Git and was not uploaded into staging. Take another fresh consistent backup immediately before cutover. + +Run against a downloaded backup, using a dependency-equipped Python 3.12 environment: + +```sh +python tools/rehearse_premium_migrations.py --source /absolute/path/to/production-backup.sqlite3 +``` + +The utility opens the source read-only, makes a disposable backup, runs `migrate --fake-initial` on the copy, and checks model columns/foreign keys. If it fails, stop and resolve the actual schema/history mismatch before approving deployment. Never delete migration records or fake missing schema changes blindly. After the baseline transition, use committed migrations normally. Back up production again immediately before any eventual migration. + +### 5. Approve the reviewed release and a later coordinated cutover + +After green CI, sandbox/real-game acceptance, and the current-backup rehearsal, review the three PRs together. Explicit approval to merge/deploy remains a separate step. At cutover: pause new launches, drain legacy servers, back up/migrate the website, start the orchestrator, then switch the bot to the matching release. Keep public discovery disabled during the initial beta. Record all deployed SHAs. + +The actual Namecheap application currently uses Python 3.9.23 and Django 3.2.25. Python 3.12 is installed, but the live application still needs to select it. **At the authorized cutover**, use cPanel β†’ Setup Python App β†’ edit the SecondWebsite application β†’ select Python 3.12. Copy the resulting virtual-environment activation command from cPanel, verify `python --version`, and install the release requirements in that environment before migrations/restart. Do not reuse the old `3.9/bin/activate` command or assume changing the SSH shell's Python changes Passenger. [Namecheap's Python application settings](https://www.namecheap.com/support/knowledgebase/article.aspx/10048/2182/how-to-work-with-python-app/). + +The fresh production database has no subscriptions tables yet; the migration seeds a default Host plan. Configure the approved Supporter ($5, 360 credits, 120-minute cap) and VIP ($12, 1,500 credits, 240-minute cap) plans and their production Polar IDs explicitly, then deactivate any unintended default plan before exposing checkout. Staging's mapped products and customized plans are not present in production. + +**The existing website workflow deploys automatically after a push to `main`. Merging its PR is therefore a deployment trigger. Keep it unmerged until the coordinated cutover is authorized, or explicitly pause that workflow first.** + +Install and verify these recurring tasks on the actual host at cutover, using its Python environment and environment variables: + +```cron +*/1 * * * * cd /absolute/path/to/website && /absolute/path/to/python manage.py sync_polar_usage +*/2 * * * * cd /absolute/path/to/website && /absolute/path/to/python manage.py expire_premium_sessions +``` + +Avoid overlapping scheduler runs; capture output and alert on failed usage/webhooks, an accumulating callback outbox, and stale open sessions. Retry corrected failed entitlement events with `python manage.py replay_subscription_webhooks`. Run `python manage.py check_premium_launch` for secret-safe local prerequisite checks; it does not contact external services or replace acceptance testing. + +Switching from sandbox to production requires production product/meter/benefit IDs and keys, verification of a controlled paid lifecycle, and a separate enablement decision. Do not reuse sandbox IDs. Remove the navbar hiding only after the beta succeeds. + +## Developer verification + +```sh +# Website: Python 3.12 with requirements.txt installed +python manage.py makemigrations --check --dry-run +python manage.py check +python -m pytest + +# Bot: Python 3.10 with requirements.txt installed +python -m unittest discover -s tests -v +python -m unittest test_regex_log -v + +# Orchestrator: Node 22 +npm ci +npm run check + +# Local cross-service acceptance (orchestrator must already be built) +ORCHESTRATOR_REPO=/absolute/path/to/xRCServerOrchestrator python -m pytest subscriptions/test_orchestrator_integration.py -o addopts='' +``` + +Use dummy settings-import secrets for CI/local tests; no real Polar or Discord credentials are needed. The orchestrator CI also checks out a matching website candidate branch, falling back to website main once the coordinated work is integrated. Production deployment workflows are not invoked by release-branch pushes. diff --git a/events/migrations/0001_initial.py b/events/migrations/0001_initial.py new file mode 100644 index 0000000..8953f1a --- /dev/null +++ b/events/migrations/0001_initial.py @@ -0,0 +1,110 @@ +# Generated by Django 3.2.25 on 2026-05-28 04:36 + +from django.db import migrations, models +import django.db.models.deletion + + +class Migration(migrations.Migration): + + initial = True + + dependencies = [ + ] + + operations = [ + migrations.CreateModel( + name='ChampionshipPoints', + fields=[ + ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('player_name', models.CharField(max_length=25)), + ('event_1', models.IntegerField(default=0)), + ('event_2', models.IntegerField(default=0)), + ], + ), + migrations.CreateModel( + name='Event', + fields=[ + ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('name', models.CharField(max_length=25)), + ('start_time', models.DateTimeField()), + ('end_time', models.DateTimeField()), + ], + ), + migrations.CreateModel( + name='Ranking', + fields=[ + ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('player_name', models.CharField(max_length=25)), + ('ranking_points', models.IntegerField()), + ('time_set', models.DateTimeField(blank=True, null=True)), + ('event', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='events.event')), + ], + ), + migrations.CreateModel( + name='Player', + fields=[ + ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('player_name', models.CharField(max_length=25)), + ('event', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='events.event')), + ], + ), + migrations.CreateModel( + name='Match', + fields=[ + ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('match_number', models.IntegerField(blank=True, null=True)), + ('match_type', models.CharField(choices=[('q', 'Qualifications'), ('qf', 'Quarterfinals'), ('sf', 'Semifinals'), ('f', 'Finals')], default='q', max_length=2)), + ('red1', models.CharField(max_length=25)), + ('red2', models.CharField(max_length=25)), + ('red3', models.CharField(max_length=25)), + ('blue1', models.CharField(max_length=25)), + ('blue2', models.CharField(max_length=25)), + ('blue3', models.CharField(max_length=25)), + ('red1_redcard', models.BooleanField(default=False)), + ('red2_redcard', models.BooleanField(default=False)), + ('red3_redcard', models.BooleanField(default=False)), + ('blue1_redcard', models.BooleanField(default=False)), + ('blue2_redcard', models.BooleanField(default=False)), + ('blue3_redcard', models.BooleanField(default=False)), + ('red1_surrogate', models.BooleanField(default=False)), + ('red2_surrogate', models.BooleanField(default=False)), + ('red3_surrogate', models.BooleanField(default=False)), + ('blue1_surrogate', models.BooleanField(default=False)), + ('blue2_surrogate', models.BooleanField(default=False)), + ('blue3_surrogate', models.BooleanField(default=False)), + ('red1_contribution', models.IntegerField(blank=True, null=True)), + ('red2_contribution', models.IntegerField(blank=True, null=True)), + ('red3_contribution', models.IntegerField(blank=True, null=True)), + ('blue1_contribution', models.IntegerField(blank=True, null=True)), + ('blue2_contribution', models.IntegerField(blank=True, null=True)), + ('blue3_contribution', models.IntegerField(blank=True, null=True)), + ('red_score', models.IntegerField(blank=True, null=True)), + ('red_climb_rp', models.BooleanField(blank=True, null=True)), + ('red_wheel_rp', models.BooleanField(blank=True, null=True)), + ('red_auto_points', models.IntegerField(blank=True, null=True)), + ('red_teleop_points', models.IntegerField(blank=True, null=True)), + ('red_endgame_points', models.IntegerField(blank=True, null=True)), + ('red_power_cells', models.IntegerField(blank=True, null=True)), + ('blue_score', models.IntegerField(blank=True, null=True)), + ('blue_climb_rp', models.BooleanField(blank=True, null=True)), + ('blue_wheel_rp', models.BooleanField(blank=True, null=True)), + ('blue_auto_points', models.IntegerField(blank=True, null=True)), + ('blue_teleop_points', models.IntegerField(blank=True, null=True)), + ('blue_endgame_points', models.IntegerField(blank=True, null=True)), + ('blue_power_cells', models.IntegerField(blank=True, null=True)), + ('event', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='events.event')), + ], + ), + migrations.CreateModel( + name='ElimsAlliance', + fields=[ + ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('alliance_number', models.IntegerField(blank=True, null=True)), + ('player1', models.CharField(max_length=25)), + ('player2', models.CharField(max_length=25)), + ('player3', models.CharField(max_length=25)), + ('advancement', models.CharField(choices=[('qf', 'QF'), ('sf', 'SF'), ('f', 'F'), ('w', 'W')], default='qf', max_length=25)), + ('event', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='events.event')), + ], + ), + ] diff --git a/events/migrations/__init__.py b/events/migrations/__init__.py new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/events/migrations/__init__.py @@ -0,0 +1 @@ + diff --git a/highscores/migrations/0001_initial.py b/highscores/migrations/0001_initial.py new file mode 100644 index 0000000..8a57cd6 --- /dev/null +++ b/highscores/migrations/0001_initial.py @@ -0,0 +1,80 @@ +# Generated by Django 3.2.25 on 2026-05-28 04:36 + +from django.conf import settings +from django.db import migrations, models +import django.db.models.deletion + + +class Migration(migrations.Migration): + + initial = True + + dependencies = [ + migrations.swappable_dependency(settings.AUTH_USER_MODEL), + ] + + operations = [ + migrations.CreateModel( + name='ExemptedIP', + fields=[ + ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('ip', models.CharField(max_length=45)), + ('reason', models.CharField(blank=True, max_length=200, null=True)), + ], + ), + migrations.CreateModel( + name='Leaderboard', + fields=[ + ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('name', models.CharField(max_length=25)), + ('robot', models.CharField(max_length=25)), + ('game', models.CharField(max_length=25)), + ('game_slug', models.CharField(max_length=5)), + ('auto_or_teleop', models.CharField(default='TELE', max_length=4)), + ('message', models.CharField(blank=True, max_length=200, null=True)), + ], + ), + migrations.CreateModel( + name='Score', + fields=[ + ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('score', models.IntegerField()), + ('time_set', models.DateTimeField(auto_now_add=True)), + ('source', models.URLField()), + ('approved', models.BooleanField(default=False)), + ('clean_code', models.CharField(max_length=4000)), + ('decrypted_code', models.CharField(blank=True, max_length=2000, null=True)), + ('client_version', models.CharField(blank=True, max_length=20, null=True)), + ('time_of_score', models.CharField(blank=True, max_length=30, null=True)), + ('robot_position', models.CharField(blank=True, max_length=20, null=True)), + ('time_data', models.TextField(blank=True, null=True)), + ('ip', models.CharField(blank=True, max_length=45, null=True)), + ('leaderboard', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='highscores.leaderboard')), + ('player', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL)), + ], + ), + migrations.CreateModel( + name='CleanCodeSubmission', + fields=[ + ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('clean_code', models.CharField(max_length=600)), + ('score', models.IntegerField()), + ('time_set', models.DateTimeField(auto_now_add=True)), + ('ip', models.CharField(blank=True, max_length=45, null=True)), + ('leaderboard', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to='highscores.leaderboard')), + ('player', models.ForeignKey(on_delete=django.db.models.deletion.CASCADE, to=settings.AUTH_USER_MODEL)), + ], + ), + migrations.AddIndex( + model_name='score', + index=models.Index(fields=['leaderboard'], name='highscores__leaderb_ad4364_idx'), + ), + migrations.AddIndex( + model_name='score', + index=models.Index(fields=['player'], name='highscores__player__3776b0_idx'), + ), + migrations.AddIndex( + model_name='score', + index=models.Index(fields=['approved'], name='highscores__approve_054a97_idx'), + ), + ] diff --git a/highscores/migrations/__init__.py b/highscores/migrations/__init__.py new file mode 100644 index 0000000..e69de29 diff --git a/home/migrations/0001_initial.py b/home/migrations/0001_initial.py new file mode 100644 index 0000000..b5f9d0a --- /dev/null +++ b/home/migrations/0001_initial.py @@ -0,0 +1,38 @@ +# Generated by Django 3.2.25 on 2026-05-28 04:36 + +from django.db import migrations, models + + +class Migration(migrations.Migration): + + initial = True + + dependencies = [ + ] + + operations = [ + migrations.CreateModel( + name='HistoricEvent', + fields=[ + ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('name', models.CharField(max_length=50)), + ('date', models.DateField()), + ('youtube_url', models.URLField(blank=True, null=True)), + ('first_place', models.CharField(max_length=100)), + ('second_place', models.CharField(blank=True, max_length=100, null=True)), + ], + ), + migrations.CreateModel( + name='Staff', + fields=[ + ('id', models.BigAutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')), + ('name', models.CharField(max_length=50)), + ('title', models.CharField(max_length=50)), + ('image_url', models.URLField()), + ('bio', models.TextField()), + ('linkedin_url', models.URLField(blank=True, null=True)), + ('github_url', models.URLField(blank=True, null=True)), + ('email', models.EmailField(max_length=254)), + ], + ), + ] diff --git a/home/migrations/__init__.py b/home/migrations/__init__.py new file mode 100644 index 0000000..8b13789 --- /dev/null +++ b/home/migrations/__init__.py @@ -0,0 +1 @@ + diff --git a/home/templates/home/base.html b/home/templates/home/base.html index c19e808..a9a30bc 100644 --- a/home/templates/home/base.html +++ b/home/templates/home/base.html @@ -243,6 +243,7 @@ +