anthorob
91b6de708d
Unified paths in guild-related endpoints to include consistent `{guildId}` structure, improving endpoint clarity and alignment with REST routing conventions. Added centralized `MusicAccess` utility to streamline music feature permission checks, replacing scattered logic in `MusicCommand`. Updated OpenAPI documentation and added tests for new and updated behaviors.
53 lines
2.7 KiB
Markdown
53 lines
2.7 KiB
Markdown
# HTTP Web API
|
|
|
|
**Package:** `me.bobert.netneutrality.platform.web` (client module) and
|
|
`me.bobert.netneutrality.platform.web.server` (server).
|
|
**Server:** JDK built-in `com.sun.net.httpserver.HttpServer` (no external web framework).
|
|
|
|
The bot exposes a small internal HTTP API for health monitoring, control, and guild introspection —
|
|
intended for an external dashboard/companion, not for end users in Discord.
|
|
|
|
## Server startup
|
|
|
|
`WebApi` is a [`Lifecycle`](utilities-and-bootstrap.md#applicationcontext--lifecycle) component
|
|
(priority 70) registered in [`App.buildContext()`](architecture.md#startup-lifecycle).
|
|
It receives `SettingsProvider`, `GuildServiceProvider`, and suppliers for the live `JDA` /
|
|
shutdown callback via its constructor. On `start()` it:
|
|
|
|
- reads the port from `NETNEUTRALITY_API_PORT` (default `9000`),
|
|
- creates an `HttpServer` bound to that port,
|
|
- installs an `Executor` backed by a fixed thread pool of 10 threads named via
|
|
[`BaseThreadFactory`](threading.md),
|
|
- registers the handler contexts (below), and
|
|
- starts the server.
|
|
|
|
On `stop()` the server and its executor are shut down gracefully.
|
|
|
|
## Handler model
|
|
|
|
`AbstractHandler` (implements `HttpHandler`) is the base for all handlers and provides helpers such as
|
|
`sendJsonResponse(...)` and `sendStringResponse(...)`. Concrete handlers extend it and are mounted at
|
|
a path prefix.
|
|
|
|
| Handler | Base path | Endpoints |
|
|
|---|---|---|
|
|
| `RootHandler` | `/` | Simple HTML "OK" landing response. |
|
|
| `GuildHandler` | `/guilds` | `/guilds/owner` — guild ids + owner ids (JSON); `/guilds/{guildId}/channels` — text channels (JSON); `/guilds/{guildId}/roles` — roles (JSON). |
|
|
| `ActionHandler` | `/actions` | `/actions/status` — JDA health + gateway ping; `/actions/shutdown` — graceful shutdown. |
|
|
| `SettingsHandler` | `/settings` | `/settings/catalog` — every known setting with its default value and description; `/settings/current/{guildId}` — current guild settings; `/settings/reload/{guildId}` — invalidate & reload the settings cache. |
|
|
|
|
The action/guild handlers read live state from the [`JDA`](architecture.md) instance and from the
|
|
[persistence services](persistence.md#service-layer) (e.g. `GuildSettingService` for the settings
|
|
endpoints).
|
|
|
|
## HTTP client — `WebModule`
|
|
|
|
`WebModule` wraps an `OkHttpClient` for the bot's own outbound HTTP calls (e.g. checking for updates
|
|
via GitLab). It keeps a small `LinkedHashMap`-based response cache limited to 50 entries.
|
|
|
|
## Notes
|
|
|
|
- There is no authentication layer documented on these endpoints; the API is expected to be bound to a
|
|
trusted/internal network (e.g. within the Docker network). `/actions/shutdown` is destructive, so the
|
|
port should not be exposed publicly.
|