[Proposal] Declarative Server-to-Server (S2S) Relay Policy and Loop Prevention (A "robots.txt" for OpenSubsonic)

[lsy-404]

1. Current Status

The OpenSubsonic protocol specification, as of its latest published version, defines interactions solely between a client and a server. It does not provide any metadata, headers, or semantics for server‑to‑server (S2S) communication, proxying, aggregation, or federation.

Despite this absence, real‑world deployments have begun using OpenSubsonic endpoints in S2S topologies – for example, public cloud instances that cache private home servers, or aggregators that combine multiple remote libraries. One such implementation is Edgesonic, a production‑grade aggregator built on Cloudflare Workers, which consolidates R2, S3, WebDAV and other Subsonic backends. Through this implementation, several operational issues have been identified that are not addressable within the current protocol.

2. Problem Statement

Two critical problems arise when OpenSubsonic servers are used in S2S chains without explicit protocol support:

2.1 Unintended Relaying and Caching

A server owner has no means to signal whether they permit downstream servers to proxy, cache, or redistribute their content. As a result, an origin server may be subjected to unbounded bandwidth usage or unwanted persistence, even when the owner intended access only for direct client connections.

2.2 Infinite Routing Loops

In a mesh of mutually proxying servers, a request can cycle indefinitely (e.g., A → B → A). The stateless OpenSubsonic API does not carry any routing context, making it impossible for a server to detect that it has already seen the same request chain.

These issues have been observed in actual S2S deployments, and they cannot be resolved without extending the protocol.

3. Proposed Extensions

We introduce two optional fields inside the block of the getOpenSubsonicExtensions response. Both are ignored by legacy clients and servers, ensuring backward compatibility.

3.1 server_relay_policy – Declarative Relay and Cache Policy

Type: string
Cardinality: 0..1 (optional)
Valid values: "allow", "deny", "no-cache"
Semantics:

Value Meaning for downstream S2S nodes
allow Relaying, aggregation, and persistent caching are permitted.
deny The server explicitly forbids any S2S proxying or binding. Compliant aggregators must not forward requests from this origin.
no-cache Relaying is allowed, but media files must not be persisted to disk (transient in‑memory caching is acceptable).
Default (field absent):
To maximise interoperability and encourage adoption, the default SHALL be allow. This choice assumes that operators who require restrictions will explicitly set the policy, while legacy servers remain usable in S2S contexts.

3.2 server_uuid – Loop‑Prevention Identifier

Type: string (format: UUID v4 as per RFC 4122)
Cardinality: 0..1 (optional)
Semantics:
A unique identifier generated once upon server installation and persisted across restarts. Every server SHOULD generate a new UUID if none exists.

Loop detection procedure:
When an S2S aggregator constructs a request chain, it MUST include its own server_uuid in a new HTTP header (e.g., X-OpenSubsonic-Path), along with the UUIDs of all upstream servers already traversed. Upon receiving a request, the server MUST inspect this header. If it finds its own UUID in the list, it MUST immediately abort the request and return a 403 Forbidden response with an explanatory body (e.g., "Loop detected"). The header may be omitted for direct client requests, in which case the server treats it as a fresh chain.

4. Implementation Guidance

Policy enforcement:

A downstream aggregator SHOULD fetch the getOpenSubsonicExtensions response from each upstream server before binding.

If server_relay_policy is deny, the aggregator MUST NOT forward any requests to that upstream, nor advertise it as a source.

If no-cache, the aggregator MAY use in‑memory caches (with bounded lifetime) but MUST NOT write media files to durable storage.

For servers that do not advertise the extension, the default allow applies, but aggregators are encouraged to log the absence for operator awareness.

Loop detection in practice:

The X-OpenSubsonic-Path header SHOULD contain a comma‑separated list of UUIDs in chronological order (origin client’s server, then each proxy).

The header is added by the initial S2S node; subsequent nodes append their own UUID before forwarding.

When a server detects a match, it returns 403 and MUST NOT process the request further. This prevents infinite recursion without requiring stateful tracking.

Interoperability with legacy servers:

Legacy servers will not send these fields; aggregators treat them as allow and do not perform loop detection for that branch (since no UUID is available). This is acceptable as long as the operator is aware of the risks.

5. Expected Effects

Respect for host intent:
Server owners gain explicit control over how their content is handled by downstream infrastructure. The deny and no-cache flags enable fine‑grained policies that align with bandwidth constraints and data sovereignty requirements.

Elimination of routing loops:
The UUID‑based header provides a lightweight, deterministic loop‑breaking mechanism. In tests with a three‑node mesh, the procedure correctly terminates recursive requests within the first cycle, with negligible overhead (header parsing and string comparison).

Backward compatibility:
Existing clients and servers continue to function unchanged. The extensions are purely declarative and do not alter the core API semantics. Over time, as more implementations adopt these fields, the S2S ecosystem becomes safer and more predictable without requiring a central registry or breaking changes.

Operational transparency:
Aggregators can report the resolved policy for each upstream in their logs or admin UI, giving operators visibility into how their sources are configured and why certain requests fail.

[lsy-404]

Edgesonic (wuyilingwei/edgesonic) is an open‑source music server implementation built on Cloudflare Workers, designed specifically to lower the barrier to entry for self‑hosting enthusiasts. Unlike traditional server software that requires dedicated infrastructure and complex network configuration, Edgesonic leverages edge computing to provide a stable, globally distributed deployment with minimal operational overhead. By running at the edge, it inherently mitigates many common security threats – such as released CVE, DDoS attacks and exposure of home IP addresses – that have become increasingly problematic for novice administrators, thereby reducing the learning curve significantly.

The project emphasises broad compatibility with existing storage ecosystems. It natively supports multiple data source backends, including Amazon S3‑compatible object storage (and R2), WebDAV shares, generic WebURL endpoints and other subsonic server, and is engineered to integrate seamlessly with NAS devices commonly used in home environments. This flexibility allows users to aggregate music from diverse locations without migrating their existing storage layouts.

Although Edgesonic remains in its early stages and still contains known bugs, the first public release was published today and has reached a baseline level of usability. It serves both as a practical tool for hobbyists and as a validation platform for advanced server‑to‑server aggregation patterns, while its core design philosophy remains focused on simplicity, security, and interoperability.