Drop Windows support

.github/workflows/build.yml

@@ -13,13 +13,8 @@ concurrency:
 
 jobs:
   build:
-    name: Build (${{ matrix.os }})
-    runs-on: ${{ matrix.os }}
-
-    strategy:
-      fail-fast: false
-      matrix:
-        os: [ubuntu-latest, windows-latest]
+    name: Build
+    runs-on: ubuntu-latest
 
     env:
       VITE_ENABLE_TASKS: true
@@ -37,43 +32,36 @@ jobs:
         manifest-path: pyproject.toml
 
     - name: Install dependencies
-      shell: bash
       run: |
         set -eux
         pixi run dev-install
 
     - name: Lint
-      if: matrix.os == 'ubuntu-latest'
       run: |
         set -eux
         pixi run node-prettier-check && pixi run node-eslint-check
 
     - name: Test the frontend
-      shell: bash
       run: |
         set -eux
         pixi run test-frontend
 
     - name: Test the backend
-      shell: bash
       run: |
         set -eux
         pixi run test-backend
 
     - name: Build the frontend
-      shell: bash
       run: |
         set -eux
         pixi run node-build
 
     - name: Package the app
-      if: matrix.os == 'ubuntu-latest'
       run: |
         set -eux
         pixi run pypi-build
 
     - name: Upload package to GH
-      if: matrix.os == 'ubuntu-latest'
       uses: actions/upload-artifact@v4
       with:
         name: extension-artifacts

README.md

@@ -50,6 +50,7 @@ Fileglancer has a React front-end and a FastAPI backend. Uvicorn is used to mana
 
 - [User guide](https://janeliascicomp.github.io/fileglancer-docs/)
 - [Developer guide](docs/Development.md)
+- [Structured logging](docs/StructuredLogging.md)
 
 ## Related repositories
 

docs/StructuredLogging.md

@@ -0,0 +1,52 @@
+# Structured Logging
+
+Setting `log_format: json` (or `FGC_LOG_FORMAT=json`) makes Fileglancer write one JSON object per line to stdout instead of human-readable text. The field names follow the [Elastic Common Schema](https://www.elastic.co/guide/en/ecs/current/index.html) (ECS), so Kibana's built-in visualizations understand them without any mapping work.
+
+The default remains `text`; nothing changes unless you turn this on. Turn it on in production, leave it off for development.
+
+## What gets logged
+
+Every log record carries `@timestamp`, `log.level`, `log.logger`, `message`, `service.name`, `service.version` and `process.pid`. Records emitted while serving a request also carry `trace.id`, which is returned to the client in the `x-request-id` response header — so a user reporting a problem can quote an id that pulls up every line for that request, including the ones logged inside the handler.
+
+One access line is logged per request, tagged `event.dataset: fileglancer.access`, with:
+
+| Field | Notes |
+|---|---|
+| `event.duration` | Request duration in **nanoseconds** (the ECS unit). |
+| `http.request.method`, `http.version` | |
+| `http.response.status_code` | |
+| `http.response.body.bytes` | Present when the response declared a Content-Length. |
+| `url.path`, `url.query`, `url.domain` | Path is logged as the client encoded it. |
+| `client.ip`, `client.port` | Corrected for the reverse proxy when running behind one. |
+| `user_agent.original` | |
+| `user.name` | Session or API-token user, absent when unauthenticated. |
+| `labels.token_id` | Present on API-token requests; the id to revoke. |
+| `labels.endpoint` | Handler function name. Group latency by this — raw paths have unbounded cardinality and are useless to aggregate over. |
+| `error.type`, `error.message`, `error.stack_trace` | On records logged with an exception. |
+
+Per-user worker subprocesses log in the same format. In text mode their output is forwarded through the parent tagged `[worker:username]`; in JSON mode they write their own records straight to the shared stdout, identifiable by `process.pid`.
+
+## Shipping to Elasticsearch
+
+Fileglancer logs to stdout, so a shipper reading the container's log files needs only to parse the JSON. For Filebeat:
+
+```yaml
+filebeat.inputs:
+  - type: container
+    paths:
+      - /var/lib/docker/containers/*/*.log
+    json.keys_under_root: true
+    json.add_error_key: true
+```
+
+Since ECS field names are written as dotted keys, Elasticsearch expands them into the usual nested ECS document on ingest.
+
+## Kibana
+
+`event.duration` is a plain number, so a percentile aggregation over it gives p95/p99 directly. Set the field's format to *Duration* (input: nanoseconds) in the data view to have Kibana render it readably. Break it down by `labels.endpoint` to find a slow API route, by `user.name` to find a heavy user, or by `http.response.status_code` for error rates.
+
+## Known limitation
+
+`event.duration` is measured until the response starts, not until the last byte is sent, so file downloads are recorded as time-to-first-byte rather than transfer time. (x2s3, which serves the bulk data, does measure full transfer time.) Charting download latency here would mean rewriting the access log middleware as pure ASGI, the way x2s3's is.
+
+Uvicorn logs two lines ("Started server process", "Waiting for application startup") before it imports the app, so those stay plain text on every start. Everything after that is JSON.

docs/config.yaml.template

@@ -3,6 +3,13 @@
 #
 log_level: INFO
 
+#
+# Log output format: 'text' for human-readable logs, or 'json' for one
+# ECS-shaped JSON object per line on stdout, ready for a log shipper to
+# forward to Elasticsearch/Kibana. See docs/StructuredLogging.md.
+#
+log_format: text
+
 #
 # Database URL (runtime - unprivileged user)
 # For SQLite: sqlite:///fileglancer.db
@@ -139,6 +146,24 @@ session_cookie_secure: true
 #   - https://ai-cryoet.int.janelia.org
 #   - https://nextflow.int.janelia.org:8444
 
+# Which API token scopes this server supports. A scope left out cannot be
+# granted to a new token, and is ignored on tokens that already hold it -- so
+# removing one here revokes the capability from existing tokens rather than
+# only affecting new ones.
+#
+# files:write and jobs:write are absent from the default shown below because
+# both amount to full access to the user's files: jobs:write runs arbitrary
+# code as the user, so it reaches every file regardless of the files:* scopes
+# granted. Enable them per server, deliberately.
+#
+# api_token_scopes:
+#   - files:read
+#   - files:write
+#   - links:read
+#   - links:write
+#   - jobs:read
+#   - jobs:write
+
 #
 # Maximum size in bytes accepted by a PUT /api/content upload. Guards the
 # streaming write path against an unbounded upload filling the disk. Set to 0