# SocketSvcProxyApi

Addon API for the SocketSVC proxy relay plugin, on both Velocity and BungeeCord/Waterfall (the relay ships as one jar for both, and this is the same API on either).

Source: https://socketsvc.vercel.app/zh-TW/api/proxy/SocketSvcProxyApi
<Callout title="Generated from source">
  Interface `com.socketsvc.proxy.api.SocketSvcProxyApi` — generated from [SocketSvcProxyApi.java](https://github.com/HippoDev03/SocketSVC/blob/main/proxy/common/src/main/java/com/socketsvc/proxy/api/SocketSvcProxyApi.java). Edit the Javadoc in the Java source, then run `pnpm gen:api`.
</Callout>

```java
package com.socketsvc.proxy.api;

public interface SocketSvcProxyApi { ... }
```

Addon API for the SocketSVC proxy relay plugin, on both Velocity and BungeeCord/Waterfall (the
relay ships as one jar for both, and this is the same API on either).

The relay is a byte-level pipe: it reads the connecting player's `uuid` query parameter,
picks a backend, and forwards bytes untouched. It never terminates the WebSocket handshake and
never decodes audio. So this API covers _routing and observation_ only — which backend a
player is relayed to, and what the relay is doing. Anything about the voice itself (speakers,
positions, per-player volume) lives on the backend's own `SocketSvcApi` /
`SocketSvcModApi`, not here, and is documented as the spatial audio API.

## Getting it

Neither Velocity nor BungeeCord has a Bukkit-style services manager, so look it up statically:
```java
SocketSvcProxyApi api = SocketSvcProxyApi.get();
if (api != null) api.addListener("my-addon", session -> ...);
```
It is `null` until the relay plugin has started, and `null` again once the proxy
shuts down, so fetch it when you need it rather than caching it in a field. Depend on the
`-api` jar with `compileOnly`; never shade it.

## Registrations outlive reloads

Resolvers and listeners are held by the plugin, not by the relay listener, so
`/ssvc-proxy reload` keeps them. Unregister on your own plugin's shutdown.

## Constants

| Constant | Description |
| --- | --- |
| `int API_VERSION = 1` | Incremented only for incompatible changes; new methods get a default instead. |

## Methods

### get

```java
static SocketSvcProxyApi get()
```

The live API, or `null` before the relay plugin has started / after it has stopped.

### register

```java
static void register(SocketSvcProxyApi api)
```

Called by SocketSVC itself; not for addons.

### isRunning

```java
boolean isRunning()
```

Whether the relay listener is currently accepting connections.

### listenAddress

```java
InetSocketAddress listenAddress()
```

The single public address the relay is bound to, or `null` when it is not running.

### activeRelays

```java
int activeRelays()
```

Connections currently being relayed.

### rejectedConnections

```java
long rejectedConnections()
```

Connections closed without being relayed since the listener started.

### backendVoiceAddresses

```java
Map<String, InetSocketAddress> backendVoiceAddresses()
```

Immutable snapshot of the configured `servers:` map: proxy server name to backend
voice address. Reflects the last successful config load, and does not include addresses a
[`ProxyBackendResolver`](/api/proxy/ProxyBackendResolver) supplies at runtime.

### setBackendResolver

```java
void setBackendResolver(String ownerId, ProxyBackendResolver resolver)
```

Registers a routing override, replacing any previous one from the same `ownerId`.
Resolvers are consulted in registration order, before the configured map.

| Parameter | Description |
| --- | --- |
| `ownerId` | your plugin's own id, used to unregister and to name you in log messages |

### clearBackendResolver

```java
void clearBackendResolver(String ownerId)
```

Removes `ownerId`'s routing override, if any.

### addListener

```java
void addListener(String ownerId, ProxyRelayListener listener)
```

Registers a lifecycle listener, replacing any previous one from the same `ownerId`.

### removeListener

```java
void removeListener(String ownerId)
```

Removes `ownerId`'s listener, if any.

### clearOwner

```java
void clearOwner(String ownerId)
```

Removes everything `ownerId` registered. Call this from your plugin's shutdown.

### reload

```java
boolean reload()
```

Re-reads `config.yml` and restarts the relay listener, exactly as
`/ssvc-proxy reload` does. Registered resolvers and listeners are kept. In-flight
relayed connections are dropped; clients reconnect with their normal backoff.

**Returns:** whether the listener came back up; on failure the relay is left stopped and the reason is in the proxy log

### isRelaying

```java
boolean isRelaying(UUID playerId)
```

Whether a connection claiming to be this player is currently being relayed. The claim is
unverified - any client can send any player's id, and the backend may refuse it a moment
later - so this is not proof the player is on voice; see [`RelaySession`](/api/proxy/RelaySession).

## Nested types

- `final class Registry`