melosso/portway v0.10.0

on GitHub

Portway 0.10.0 adds endpoint versions, deprecation headers, a health page, database backups and restore, and console settings for most environment variables. Version numbers 0.8 and 0.9 are skipped.

Before you upgrade

Check each item. Skip the items that do not apply to your instance.

1. Generated API clients. Regenerate them from /docs/openapi.json. SQL, webhook and static operations have route-based ids such as get_WMS_Bins. Each endpoint has its own tag such as CRM/Accounts. The previous document URLs redirect to /docs/openapi.json.
2. Clients that read 403 details. Remove reads of availableEnvironments, requestedEnvironment, availableScopes and requestedEndpoint. These fields are removed. Every 401 and 403 returns success and error.
3. Endpoint folders named v1, v2 and so on. Rename such a folder when it sits inside another endpoint folder, for example to orders-v1. Portway 0.10 loads it as a version of the parent endpoint. A v1 folder replaces the parent's entity.json.
4. Settings set by environment variables. Environment variables override values saved in the console, and the console shows these settings as read-only. To manage a setting in the console, remove its environment variable.
5. The console. The console is enabled by default and accepts requests from the local network. To keep it off, set PORTWAY_WEBUI_ENABLED=false. To open it to other networks, set PORTWAY_PUBLIC_ORIGINS. On an instance without accounts, the startup log contains a one-time password for the account admin- plus eight random characters.
6. Metrics dashboards and alerts. Update queries on the portway.endpoint label. The label contains the full endpoint name, for example CRM/Accounts or Inventory/Products@v2.
7. Namespace descriptions. Move namespace text in entity.json from Documentation.TagDescription to NamespaceDescription.
8. Instances behind a reverse proxy. Add the proxy to ForwardedHeaders:KnownProxies or KnownNetworks. The OpenAPI server URL reads its scheme from trusted proxies. An untrusted proxy results in http server URLs.

No action is needed for these:

• The WebUi section in appsettings.json is renamed to Console. WebUi keys and WebUi__* variables still work and log a deprecation warning.
• Unprefixed environment variables such as Telemetry__Provider still work next to their new PORTWAY_* names and log a deprecation warning.
• PORTWAY_ADMIN_KEY is deprecated. It still enables the console and is not used for sign-in.
• The GET:{endpoint} token scope form is removed. It was never enforced. Existing tokens are unchanged.
• The first start adds columns to auth.db and metrics.db.

New

• Endpoint versions. A v{n} folder inside an endpoint folder defines a version, served at /api/{env}/v{n}/.... A token scope selects a version with @v{n}. Each version has its own MCP tool and OpenAPI operations.
• Deprecation headers. DeprecatedSince and Sunset in entity.json set the matching response headers. A deprecated version links to its successor.
• Health page. Displays success rate, errors and latency percentiles per environment, endpoint, version and method.
• Backups. A daily snapshot contains auth.db, mcp.db, environments/ and endpoints/. Seven snapshots are kept by default. The console creates, downloads and restores snapshots. A restore applies at the next start.
• Database health. The daily maintenance run checks each database for corruption. The console displays the result per database.
• Console settings for telemetry, backups and maintenance. A setting set by an environment variable displays the variable name.
• Token rotation and last use. The token edit sheet rotates a token. The token list displays the last use.
• Markdown API reference for LLMs at /docs/openapi.md. Enabled by default. Disable it in the console or with PORTWAY_OPENAPI_MARKDOWN=false (OpenApi:ServeMarkdown).
• OpenAPI settings in the console: namespace grouping, MCP badges and OData badges.
• PORTWAY_* names for the common environment variables, listed in the environment variable reference.
• Sortable users table and the signed-in e-mail in the account menu. /docs uses Scalar 1.72.4.

Fixes

• Security: An out-of-scope request returns 403 with Access denied to endpoint. The response omits the token's endpoints and environments.
• Security: The OpenAPI server URL reads X-Forwarded-Proto from trusted proxies (ForwardedHeaders:KnownProxies).
• Security: Request metrics label configured endpoints and allowed environments. Other requests have an empty label.
• Security: Token scopes are validated on create and update.
• Security: /docs HTML-encodes the configured title and footer.
• Security: appsettings.json contains no placeholder admin key.
• Security: The console sign-in lockout counts parallel attempts.
• Security: Token changes and revocations apply to the next request.
• Security: Environment settings saves are atomic. Requests during a save keep environment authentication.
• Fix: Hot reload applies to composite steps, SQL column metadata and environments/settings.json.
• Fix: A partly saved entity.json keeps the last valid endpoint definition.
• Fix: Parallel file downloads return the complete, current file.
• Fix: A client disconnect cancels the running SQL read.
• Fix: Requests continue while Redis is slow or a reload runs.
• Fix: Console saves work on a single-file mount of appsettings.overrides.json. The configuration reloads after each save.
• Fix: A failure before logging starts is written to the console.
• Fix: An empty OTLP endpoint or service name uses the default value.
• Fix: With PORTWAY_PATH_BASE set, SSO buttons and MCP chat include the path base once.
• Fix: The first sign-in after a cold start waits for its CSRF token.
• Fix: Header rows on the environments and endpoints pages display on one line.
• Fix: 401 responses include WWW-Authenticate.
• Fix: The OpenAPI document matches the served routes, paging headers, file schemas and security requirements. The document is about 25% smaller.
• Fix: Request metrics name namespaced and versioned endpoints. Unhandled exceptions count as 500.
• Fix: The Dockerfile builds.
• Fix: The unused MCP Apps explorer is removed.

Setup guide: documentation.

Full changelog: v0.7.0...v0.10.0