better caching

Author: Tsche

.env.example

@@ -31,7 +31,6 @@ CMD ["python", "-m", "feedback"]
 
 FROM development AS test
 
-ENV FEEDBACK_ENV=test
 COPY pyproject.toml ./
 COPY src ./src
 COPY tests ./tests
@@ -53,10 +52,7 @@ ENV VIRTUAL_ENV=/opt/venv \
     PATH=/opt/venv/bin:$PATH \
     PYTHONUNBUFFERED=1 \
     PYTHONDONTWRITEBYTECODE=1 \
-    PYTHONHASHSEED=random \
-    FEEDBACK_HOST=0.0.0.0 \
-    FEEDBACK_PORT=8080 \
-    FEEDBACK_WORKERS=1
+    PYTHONHASHSEED=random
 
 RUN apt-get update \
     && apt-get install --yes --no-install-recommends ca-certificates \

Dockerfile

@@ -24,6 +24,11 @@ The secret files must be readable by UID 10001 in the container. Root-owned mode
 `0444` is suitable because Docker bind-mounts them read-only. The application
 configuration itself is committed as `config/sites.toml`.
 
+The process is configured with explicit command-line arguments rather than
+environment variables. `python -m feedback --help` lists the config, secret-file,
+listener, proxy-trust, concurrency, and keep-alive options. Docker Compose passes
+those arguments directly and uses fixed read-only mounts.
+
 The `vps-8def0ca8` NixOS configuration imports and enables the feedback service.
 Rebuilding that host builds the image from `/srv/feedback`, starts it with Docker
 Compose, and provisions the `feedback-api.cpp.social` nginx virtual host and ACME
@@ -36,6 +41,77 @@ systemctl status feedback-service
 curl --fail --silent --show-error https://feedback-api.cpp.social/
 ```
 
+## Site mappings and metadata
+
+Each site maps a browser resource to one GitHub Discussion. The configured
+`mapping` selects the value used as the discussion lookup term and title:
+
+- `key`: the stable application-provided `resource.key` (recommended when URLs or
+  titles may change).
+- `title`: the resource title.
+- `url`: the complete canonical URL, including its origin.
+- `pathname`: only the canonical URL path, allowing equivalent pages on multiple
+  origins to share a discussion.
+- `custom`: an arbitrary consumer-provided string for custom routing schemes.
+- `number`: the numeric number of an already existing GitHub Discussion. Unlike
+  `key`, it is not a resource identifier and missing discussions are never created.
+
+The browser package exports `resourceFromDocument()`. By default it reads the
+first non-empty title from `meta[property="og:title"]` and then `<title>`, reads
+`link[rel="canonical"]` when present, and otherwise uses the current location.
+Consumers can override `titleSelectors` and `canonicalSelector`, or construct a
+`Resource` directly and supply `custom`, `pathname`, or `number`. Metadata
+selection is intentionally client-side; the service only receives validated
+resource values and applies the site mapping.
+
+```ts
+const resource = resourceFromDocument({
+  key: "articles/stable-id",
+  titleSelectors: ['meta[name="feedback-title"]', 'meta[property="og:title"]', "title"],
+  canonicalSelector: 'link[rel="canonical"]',
+  custom: document.body.dataset.feedbackKey ?? "default-feedback-key",
+});
+```
+
+## Counter cache
+
+`cache_fresh_seconds` is the age at which a requested tracked counter needs an
+authoritative GitHub refresh. The default is five seconds. A batched request
+refreshes only stale resources; recently refreshed resources in the same request
+are served from SQLite. For example, if A was last refreshed 30 seconds ago and B
+three seconds ago, requesting `[A, B]` sends only A's discussion ID to GitHub and
+returns B from SQLite in the same response.
+
+`refresh_cooldown_seconds` is the minimum delay before retrying a refresh attempt
+for the same resource. It primarily prevents repeated GitHub calls after a failed
+or concurrent attempt. Concurrent requests also join the same in-flight site
+batch. The default is five seconds.
+
+`refresh_sweep_seconds` controls the low-priority full maintenance cycle. The
+default is 86400 seconds (daily). The service walks only discussions whose last
+authoritative snapshot is that old, in batches of 50 with pacing between full
+batches. Targeted requests and successful votes continue independently.
+
+Votes made through the runtime update SQLite immediately using an atomic,
+confirmed delta. These local values are tentative: they do not change the last
+GitHub-refresh timestamp, and the next successful targeted or maintenance refresh
+replaces them with GitHub's absolute counts. Counter responses use `no-cache`, so
+browsers revalidate with this service; that does not imply a GitHub request while
+the relevant snapshot remains fresh.
+
+The browser runtime keeps the last counter snapshot in local storage for up to
+seven days. Consumers can render it synchronously while the API request is in
+flight, avoiding a flash of zero counters. Snapshots contain only the site/resource
+key, discussion node ID, counts, and save time; authentication tokens are not part
+of this cache. Storage is optional and failures fall back to the network normally.
+
+Operational logs are emitted at GitHub boundaries rather than for every HTTP
+request. Reaction-refresh lines include the site, trigger (`requested` or
+`sweep`), batch size, updated-row count, and duration. Failures include safe
+GitHub status/request IDs where available. Discussion discovery/creation, OAuth
+failures, vote failures, startup, and sweep summaries are also logged. Client
+IPs, origins, resource URLs, authorization codes, and tokens are not logged.
+
 ## Local checks
 
 ```sh

README.md

@@ -6,6 +6,14 @@ services:
       context: .
       target: production
     image: feedback-service:local
+    command:
+      - --config=/run/config/sites.toml
+      - --github-app-private-key-file=/run/secrets/github-app-private-key
+      - --github-client-secret-file=/run/secrets/github-client-secret
+      - --oauth-state-hmac-key-file=/run/secrets/oauth-state-hmac-key
+      - --forwarded-allow-ips=172.17.0.1
+      - --limit-concurrency=64
+      - --keep-alive-seconds=5
     restart: unless-stopped
     init: true
     read_only: true
@@ -18,19 +26,10 @@ services:
     mem_limit: 256m
     mem_reservation: 128m
     cpus: 1.0
-    environment:
-      FEEDBACK_CONFIG: /run/config/sites.toml
-      FEEDBACK_DATA_DIRECTORY: /data/sites
-      FEEDBACK_GITHUB_APP_PRIVATE_KEY_FILE: /run/secrets/github-app-private-key
-      FEEDBACK_GITHUB_CLIENT_SECRET_FILE: /run/secrets/github-client-secret
-      FEEDBACK_OAUTH_STATE_HMAC_KEY_FILE: /run/secrets/oauth-state-hmac-key
-      FEEDBACK_FORWARDED_ALLOW_IPS: ${FEEDBACK_FORWARDED_ALLOW_IPS:-127.0.0.1}
-      FEEDBACK_LIMIT_CONCURRENCY: ${FEEDBACK_LIMIT_CONCURRENCY:-64}
-      FEEDBACK_KEEP_ALIVE_SECONDS: ${FEEDBACK_KEEP_ALIVE_SECONDS:-5}
     ports:
-      - "127.0.0.1:${FEEDBACK_HOST_PORT:-18080}:8080"
+      - "127.0.0.1:18080:8080"
     volumes:
-      - ${FEEDBACK_CONFIG_FILE:-./config/sites.toml}:/run/config/sites.toml:ro
+      - ./config/sites.toml:/run/config/sites.toml:ro
       - feedback-data:/data
     secrets:
       - github-app-private-key
@@ -61,11 +60,11 @@ services:
 
 secrets:
   github-app-private-key:
-    file: ${FEEDBACK_GITHUB_APP_PRIVATE_KEY_FILE:-./config/secrets/github-app-private-key.pem}
+    file: ./config/secrets/github-app-private-key.pem
   github-client-secret:
-    file: ${FEEDBACK_GITHUB_CLIENT_SECRET_FILE:-./config/secrets/github-client-secret}
+    file: ./config/secrets/github-client-secret
   oauth-state-hmac-key:
-    file: ${FEEDBACK_OAUTH_STATE_HMAC_KEY_FILE:-./config/secrets/oauth-state-hmac-key}
+    file: ./config/secrets/oauth-state-hmac-key
 
 volumes:
   feedback-data:

compose.deploy.yaml

@@ -10,14 +10,11 @@ services:
       - -c
       - >-
         pip install --no-deps --editable . &&
-        exec uvicorn feedback.app:app --host=0.0.0.0 --port=8080
-        --reload --no-server-header
-    environment:
-      FEEDBACK_CONFIG: /workspace/config/sites.dev.toml
-      FEEDBACK_DATA_DIRECTORY: /workspace/config/data
-      FEEDBACK_GITHUB_APP_PRIVATE_KEY_FILE: /workspace/config/secrets/github-app-private-key.pem
-      FEEDBACK_GITHUB_CLIENT_SECRET_FILE: /workspace/config/secrets/github-client-secret
-      FEEDBACK_OAUTH_STATE_HMAC_KEY_FILE: /workspace/config/secrets/oauth-state-hmac-key
+        exec python -m feedback --config=/workspace/config/sites.dev.toml
+        --github-app-private-key-file=/workspace/config/secrets/github-app-private-key.pem
+        --github-client-secret-file=/workspace/config/secrets/github-client-secret
+        --oauth-state-hmac-key-file=/workspace/config/secrets/oauth-state-hmac-key
+        --host=0.0.0.0 --port=8080
     init: true
     ports:
       - "127.0.0.1:8080:8080"
@@ -31,8 +28,6 @@ services:
       context: .
       target: test
     command: ["pytest", "-q"]
-    environment:
-      FEEDBACK_ENV: test
     init: true
     profiles: ["test"]
     read_only: true

compose.dev.yaml

@@ -12,7 +12,7 @@ http_request_timeout_seconds = 10
 
 [sites.feedback-cpp-social]
 origins = ["https://feedback.cpp.social"]
-mapping = "id"
+mapping = "key"
 repository = "cppsocial/feedback"
 repository_id = "R_kgDOUc9png"
 installation_id = 162105624

config/sites.dev.toml

@@ -10,9 +10,15 @@ http_request_timeout_seconds = 10
 
 [sites.example]
 origins = ["https://www.example.com"]
-mapping = "id"
+mapping = "key"
 repository = "example/site"
 repository_id = "replace-with-repository-node-id"
 installation_id = 1
 category = "Resources"
 category_id = "replace-with-category-node-id"
+
+# Optional cache tuning; these are the defaults.
+# cache_fresh_seconds = 5
+# refresh_cooldown_seconds = 5
+# refresh_sweep_seconds = 86400
+# max_batch_size = 100

config/sites.example.toml

@@ -10,7 +10,7 @@ http_request_timeout_seconds = 10
 
 [sites.feedback-cpp-social]
 origins = ["https://feedback.cpp.social"]
-mapping = "id"
+mapping = "key"
 repository = "cppsocial/feedback"
 repository_id = "R_kgDOUc9png"
 installation_id = 162105624
@@ -19,7 +19,7 @@ category_id = "DIC_kwDOUc9pns4DFwQt"
 
 [sites.cpp-social]
 origins = ["https://cpp.social"]
-mapping = "id"
+mapping = "key"
 repository = "cppsocial/site"
 repository_id = "R_kgDOSOfNQQ"
 installation_id = 162105624

config/sites.toml

@@ -13,17 +13,6 @@ in
       default = "/srv/feedback";
     };
 
-    port = mkOption {
-      type = types.port;
-      default = 18080;
-    };
-
-    forwardedAllowIps = mkOption {
-      type = types.str;
-      default = "172.17.0.1";
-      description = "Addresses trusted to supply forwarded headers to Uvicorn.";
-    };
-
     proxy = {
       enable = mkEnableOption "the feedback nginx virtual host" // { default = true; };
 
@@ -48,10 +37,6 @@ in
       requires = [ "docker.service" ];
       wants = [ "network-online.target" ];
       wantedBy = [ "multi-user.target" ];
-      environment = {
-        FEEDBACK_FORWARDED_ALLOW_IPS = cfg.forwardedAllowIps;
-        FEEDBACK_HOST_PORT = toString cfg.port;
-      };
       unitConfig.ConditionPathExists = "${cfg.repositoryDirectory}/compose.deploy.yaml";
       serviceConfig = {
         Type = "simple";
@@ -89,7 +74,7 @@ in
         '';
         locations = {
           "~ ^/v1/sites/[a-z0-9-]+/(?:oauth/(?:authorize|exchange)|discussions/ensure)$" = {
-            proxyPass = "http://127.0.0.1:${toString cfg.port}";
+            proxyPass = "http://127.0.0.1:18080";
             extraConfig = ''
               limit_req zone=feedback_sensitive burst=5 nodelay;
               proxy_connect_timeout 3s;
@@ -98,7 +83,7 @@ in
             '';
           };
           "/" = {
-            proxyPass = "http://127.0.0.1:${toString cfg.port}";
+            proxyPass = "http://127.0.0.1:18080";
             extraConfig = ''
               limit_req zone=feedback_general burst=30 nodelay;
               proxy_connect_timeout 3s;

deploy/nixos-module.nix

@@ -11,13 +11,9 @@
   <body>
     <main>
       <h1>Feedback integration example</h1>
-      <p>This small page exercises cached counts, GitHub authentication, direct voting, and local stars.</p>
+      <p>This page exercises batched cached counts, targeted refreshes, GitHub authentication, voting, and local stars.</p>
       <p>API: <code id="api-origin"></code></p>
-      <div class="controls" aria-label="Feedback controls">
-        <button id="up" type="button">▲ 0</button>
-        <button id="down" type="button">▼ 0</button>
-        <button id="star" type="button" aria-pressed="false">★ Star</button>
-      </div>
+      <div id="cards" class="cards"></div>
       <p id="status" role="status">Loading…</p>
     </main>
     <script src="{{EXAMPLE_SCRIPT}}"></script>