apache / apache/maka

fix(desktop): connection base URL gate is looser than the Runtime Host contract, so a rejected endpoint reports a misleading error

Open
#3,672 1 comment 0 reactions 0 assignees View on GitHub
bug help wanted
Dominant language
TypeScript
Stars
5.4k
Forks
502
Avg merge
1d 2h
Merged PRs (30d)
715

Description

## What happened

The Desktop connection forms accept `baseUrl` values that the Runtime Host will refuse, so a custom relay endpoint containing a query string, a fragment, or embedded credentials is accepted by the form, sent over IPC, and then rejected by the Host. The rejection is not classified, so the user is shown the generic fallback copy:

> 模型连接服务暂时不可用,请稍后重试。
> The model connection service is temporarily unavailable. Try again later.

That message is wrong twice over: the service is available, and retrying can never succeed. Nothing points at the endpoint field, which is the actual problem, and the field is not marked — the error lands on `field: 'form'`.

Two validators disagree about what a connection base URL is:

| Input | Desktop IPC gate (`validateConnectionBaseUrl`) | Runtime Host (`normalizeCatalogConnectionBaseUrl`) |
| --- | --- | --- |
| `https://gw.example.com/v1?api-version=2024-06` | accepted verbatim | rejected — "must not contain a query or fragment" |
| `https://user:pw@gw.example.com/v1` | accepted verbatim | rejected — "must not contain credentials" |
| `https://gw.example.com` | kept as typed | canonicalized to `https://gw.example.com/` |
| `https://Relay.Example.com/V1` | kept as typed | canonicalized to `https://relay.example.com/V1` |

`validateConnectionBaseUrl` (`packages/core/src/llm-connections.ts:602`) checks only length, `URL` parseability, and an http/https scheme allowlist, and `normalizeConnectionBaseUrl` (`:668`) documents "Trim is the only canonicalization". The Host codec (`packages/core/src/runtime-policy/connection-catalog-codec.ts:633`) additionally rejects credentials and query/fragment, canonicalizes through `URL.toString()`, and enforces a 2048-**byte** cap rather than a 2048-character one.

Both write paths use the lenient gate — `connections:create` and `connections:update` each route through `normalizeConnectionBaseUrlForIpc` (`apps/desktop/src/main/connections-ipc-validation.ts:111`, and `normalizeUpdateInput` at `apps/desktop/src/main/runtime-host-connections-ipc-main.ts:471`) — so both adding a relay and editing an existing endpoint fail the same way.

The client-side form gate does not narrow this either: `validateAddProviderDraft` (`apps/desktop/src/renderer/settings/provider-add-submission.ts:89`) only checks that a required base URL is non-empty.

## How to reproduce

1. Open Desktop → Settings → Models → Add provider.
2. Pick **自定义中转站(OpenAI Chat)** / **Custom relay (OpenAI Chat-compatible)** (`openai-compatible`).
3. Enter any API key and set the endpoint to `https://gw.example.com/v1?api-version=2024-06`.
4. Save.

Expected: the endpoint field reports, before anything is sent, that a query string is not allowed.
Actual: the form submits, the Host rejects the write, and the form shows "模型连接服务暂时不可用,请稍后重试。" with no field marked.

The same happens on an existing connection via Settings → Models → *(connection)* → 端点 → 编辑.

The three layers can be exercised directly against a built tree, which is how the table above was produced:

```js
import { normalizeCreateConnectionInputForIpc } from './apps/desktop/dist/main/connections-ipc-validation.js';
import { normalizeCatalogConnectionBaseUrl } from './packages/core/dist/runtime-policy/connection-catalog-codec.js';
import { validateAddProviderDraft } from './apps/desktop/dist/renderer/settings/provider-add-submission.js';

const url = 'https://gw.example.com/v1?api-version=2024-06';

validateAddProviderDraft({
providerType: 'openai-compatible', slug: 'my-relay', existingSlugs: [],
apiKey: 'sk-test', cloudflareAccountId: '', baseUrl: url,
});
// -> null (add-form field gate: accepted)

normalizeCreateConnectionInputForIpc({
slug: 'my-relay', name: 'My relay', providerType: 'openai-compatible',
baseUrl: url, defaultModel: 'gpt-4o',
}).baseUrl;
// -> 'https://gw.example.com/v1?api-version=2024-06' (main-process IPC gate: accepted)

normalizeCatalogConnectionBaseUrl(url, 'openai-compatible');
// -> throws: connection base URL must not contain a query or fragment
```

## Environment

- Maka commit: `3bb645e99`
- OS and version: macOS 15 (Darwin 25.5.0), Apple Silicon
- Surface: Desktop (Settings → Models add/edit forms) against a local Runtime Host
- Node.js version: 22.19.0

## Logs, screenshots, or additional context

The message the user ends up seeing is the unclassified fallback, not the Host's sentence. `providerPanelActionErrorMessage` (`apps/desktop/src/renderer/settings/provider-panel-shared.ts:56`) strips the Electron wrapper via `cleanErrorMessage`, finds no match in `shared.lastTest`, sees no CJK, and gets `''` back from `generalizedErrorMessageChinese`/`generalizedErrorMessage`, so it returns `shared.actionFallback` (`apps/desktop/src/renderer/locales/settings-provider-copy.ts:154`, `:299`).

Suggested boundary, and the one I would like to implement:

1. Make the client-side gate agree with the Host contract. `validateConnectionBaseUrl` should reject credentials and query/fragment and enforce the byte cap, so `normalizeConnectionBaseUrl` and the add-form gate inherit the same rules and the failure is raised before the IPC call. The Host stays the authority; the client stops promising something the Host will not honor.
2. Report it on the endpoint field with localized copy rather than as a form-level generic error, so the message names the rule that was broken.
3. Canonicalize on the client the same way the Host does, so a saved endpoint reads back as the value that was persisted instead of silently differing by a trailing slash or host case.

This deliberately does not relax the Host. Allowing query strings (e.g. Azure-style `?api-version=`) would be a product and security decision for `dev@maka.apache.org`, not an implementation detail; this issue is only about the client agreeing with the contract that already exists.

Related but distinct: #3405 / #3467 cover the TUI wizard being unable to create relay connections at all. This issue is about the Desktop surface that can already create them.

Contributor guide

Open the contributing guide

Research direction

Start with validateConnectionBaseUrl and normalizeConnectionBaseUrl in packages/core/src/llm-connections.ts, then trace normalizeConnectionBaseUrlForIpc in apps/desktop/src/main/connections-ipc-validation.ts and normalizeUpdateInput in apps/desktop/src/main/runtime-host-connections-ipc-main.ts. Review validateAddProviderDraft and providerPanelActionErrorMessage in the renderer; done means both add and edit forms reject the Host-disallowed URL shapes before IPC, show a localized endpoint-field error, and use the Host-compatible canonical value.

Written by the indexing model from the issue text.

Assessment

Tech stack
electron, typescript
Domain
desktop
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Clearly specified
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.