How `resource_urls=public` Short‑Circuits the Second Authenticated Proxy Call for IM/Embed Clients

Adding ?resource_urls=public to a WeKnora API request rewrites internal resource:// handles into time‑limited public HTTPS URLs, bypassing the secondary authenticated /files proxy call and allowing embed or IM clients to fetch assets in a single HTTP request.

In the Tencent/WeKnora codebase, embed and instant messaging (IM) clients normally receive opaque resource handles that force a second, authenticated round‑trip to retrieve file bytes. The resource_urls=public query parameter eliminates this overhead by returning direct, signed URLs from the storage backend.

The Standard Two‑Step Retrieval Flow

Without the public URL flag, the server returns internal resource:// identifiers in API responses. The client must then present valid API credentials to the authenticated /files proxy endpoint to exchange these handles for downloadable content. This pattern doubles HTTP overhead and introduces unnecessary latency for every image, document, or media asset.

How resource_urls=public Transforms Resource Handles

When the server detects resource_urls=public, it invokes the storage resolver to generate cryptographically signed, time‑limited HTTPS URLs. These public URLs point directly to the object storage backend, removing the need for the authenticated proxy intermediary. Instead of opaque handles, the client receives standard https:// links that can be fetched with a simple HTTP GET and no additional authentication headers.

Implementation Points in the WeKnora Source Code

The short‑circuit logic spans client request construction and server‑side handler execution across multiple files.

Client‑Side Parameter Injection

In [client/resource_urls.go](https://github.com/Tencent/WeKnora/blob/main/client/resource_urls.go), the function applyResourceURLQuery conditionally appends the resource_urls=public query string to outgoing API calls only when the mode is explicitly set to public. This ensures the client explicitly opts into the direct‑URL behavior.

Server‑Side Handler Short‑Circuit

The critical bypass occurs in [internal/handler/embed_channel.go](https://github.com/Tencent/WeKnora/blob/main/internal/handler/embed_channel.go). At line 679, the embed request processor checks for the resource_urls=public parameter. When present, the handler skips the secondary /files proxy call entirely and returns the pre‑generated public URLs produced by the storage resolver. The inline comment explicitly notes that this parameter “short‑circuits the second authenticated proxy call.”

URL Resolution and Parsing Infrastructure

Supporting this flow, [internal/handler/session/resource_urls.go](https://github.com/Tencent/WeKnora/blob/main/internal/handler/session/resource_urls.go) parses the incoming query parameter and selects the appropriate URL generation mode, while [internal/storageurl/mode.go](https://github.com/Tencent/WeKnora/blob/main/internal/storageurl/mode.go) implements the resolver that converts internal handles into signed external URLs.

Practical Implementation Examples

The following examples demonstrate how to trigger the single‑request behavior for hybrid search and embed channel endpoints.

Fetch hybrid‑search results with public URLs:

curl -X POST "https://your-host/api/v1/knowledge-bases/kb-1/hybrid-search?resource_urls=public" \
     -H "X-API-Key: $FULL_ACCESS_KEY" \
     -d '{"keyword":"example"}'

Retrieve embed channel messages with direct links:

curl -X GET "https://your-host/api/v1/embed/12345/messages?resource_urls=public" \
     -H "Authorization: Bearer <embed-token>"

In both cases, the JSON response contains https://... links rather than resource://... handles, allowing the client to download files with one direct GET request.

Performance and Architecture Benefits

• Reduced Latency: Eliminates the second HTTP round‑trip to the authenticated proxy.
• Lower Server Load: Decreases traffic to the API key validation layer.
• Simplified Client Logic: Embed clients treat assets as standard web resources without managing proxy authentication headers for each byte request.

Summary

• WeKnora’s default behavior returns resource:// handles requiring an authenticated /files proxy call.
• The resource_urls=public parameter triggers a server‑side rewrite to signed, time‑limited public URLs.
• The short‑circuit is implemented in internal/handler/embed_channel.go (line 679) and supported by client/resource_urls.go and internal/storageurl/mode.go.
• Clients receive direct https:// links and fetch assets in a single request, improving performance for IM and embed integrations.

Frequently Asked Questions

What happens if I omit resource_urls=public in an embed request?

The server returns internal resource:// handles. Your client must then make a second, authenticated request to the /files proxy endpoint, presenting a valid API key or Bearer token to retrieve the actual file bytes.

Are the public URLs generated by this parameter secure?

Yes. According to the implementation in internal/storageurl/mode.go, the URLs are cryptographically signed and time‑limited. They expire after a short duration, preventing unauthorized long‑term access while eliminating the need for per‑request API key validation.

Does this optimization apply to regular API clients or only embed channels?

While the short‑circuit logic is explicitly implemented in internal/handler/embed_channel.go, the same URL transformation applies to any client that requests public URLs, including standard IM chat clients. The server performs the same rewrite whenever the parameter is present, regardless of the client type.

Which source files control the URL transformation logic?

The transformation is orchestrated across four key files: client/resource_urls.go (injects the parameter), internal/handler/session/resource_urls.go (parses the mode), internal/handler/embed_channel.go (executes the short‑circuit), and internal/storageurl/mode.go (resolves handles to signed public URLs).

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}