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

> Discover how resource_urls=public short-circuits the second authenticated proxy call for IM/embed clients. Fetch assets in a single HTTP request by rewriting resource:// handles.

- Repository: [Tencent/WeKnora](https://github.com/tencent/WeKnora)
- Tags: internals
- Published: 2026-09-12

---

**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)](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)](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)](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)](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:

```bash
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:

```bash
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`](https://github.com/Tencent/WeKnora/blob/main/internal/handler/embed_channel.go) (line 679) and supported by [`client/resource_urls.go`](https://github.com/Tencent/WeKnora/blob/main/client/resource_urls.go) and [`internal/storageurl/mode.go`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/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`](https://github.com/Tencent/WeKnora/blob/main/client/resource_urls.go) (injects the parameter), [`internal/handler/session/resource_urls.go`](https://github.com/Tencent/WeKnora/blob/main/internal/handler/session/resource_urls.go) (parses the mode), [`internal/handler/embed_channel.go`](https://github.com/Tencent/WeKnora/blob/main/internal/handler/embed_channel.go) (executes the short‑circuit), and [`internal/storageurl/mode.go`](https://github.com/Tencent/WeKnora/blob/main/internal/storageurl/mode.go) (resolves handles to signed public URLs).