netneutrality/docs/web-api.md

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 component (priority 70) registered in App.buildContext(). 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,
• 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/channels/{guildId} — text channels (JSON); /guilds/roles/{guildId} — 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 instance and from the persistence services (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.