README
¶
Protocol wrappers
This directory contains the Go module/runtime SDK for FlexModule v2. Generated
wire messages live in ../proto; host authorization and
execution live in ../internal/runtime and ../internal/backend, not in a module-side SDK.
Packages
| Package | Responsibility |
|---|---|
core-v2 |
Application protocol 2 bootstrap, Hook lifecycle/event dispatch, exact JSON config, FileTransfer client, common errors and work references |
discord-v2 |
Typed Discord clients, event/domain conversion, presence-aware views, credential handles, interaction routes and optional voice-job client |
media/opus |
Optional module-side bounded FFmpeg/Opus processing; not a runtime backend or ordinary bot prerequisite |
The removed core-v1/discord-v1, old conversion utilities and helper-service
experiment are not compatibility paths. Rebuild runtime and modules together;
there is no mixed-version fallback.
The public Go module remains github.com/thirdscam/chatanium-flexmodule;
shared/ and proto/ imports are unchanged. Host-only packages under
internal/ are not module-author APIs. Discord types use the
github.com/bwmarrin/discordgo import path. The root go.mod pins upstream
v0.29.1-0.20260214123928-f43dd94faaac and replaces it with
./.tools/deps/discordgo; the nested media modules use the same requirement and
../../.tools/deps/discordgo replacement. This is the
maintained upstream-plus-patches workflow,
not a dependency on a published fork or an unpatched-upstream fallback.
For host/runtime builds and the in-repository modules, run make prepare-sdk
from the repository root before direct Go commands. Repository build entry
points hold a shared SDK lease across compiler consumption. For raw Go commands,
prepare first and avoid concurrent dependency preparation; see the
root build instructions.
third_party/discordgo/upstream.sum, not consumer go.sum, is the preparation
checksum authority.
Go replacements do not propagate to downstream consumers. Public shared/
users can consume the pinned upstream github.com/bwmarrin/discordgo DTO module
normally, without an SDK replacement; the host runtime needs the maintained
patches. A separate consumer module replacing only the FlexModule root was
tidied and ran a UserToProto/ProtoToUser round-trip using the original
upstream module and verified checksums, with no DiscordGo replacement. This is
bounded public-consumer evidence, not proof of host or live Discord behavior.
These source boundaries do not change OCI manifests, ModuleIDs or grant checks.
Transport and lifecycle
The privileged supervisor launches immutable module images through Docker/runsc. The unprivileged runtime's manager uses the authenticated go-plugin AutoMTLS/multiplex transport; modules are not launched directly as host subprocesses. Each instance has a primary Hook connection and one fixed reverse helper connection, broker ID 1, shared by core/file and registered backends. The reverse-helper allowance is lifetime-scoped, not reset for each operation, service or reconnect. Losing that transport fails the instance. An SDK helper does not establish a new connection or invent authorization.
Modules implement GetManifest, GetStatus, OnStage and OnEvent using the
context-aware core-v2 contract. The canonical embedded manifest must equal the
image label declaration after authenticated bootstrap. INIT validates module
configuration and actual grants, opens owned resources and publishes
readiness. START returns without blocking on RUNNING-only work. The runtime
commits RUNNING after START; its bounded activation gate handles eligible
early helper calls. Events are finite, ordered deliveries. DRAIN/STOP cancel,
join and release owned work within their deadlines.
Open module storage using the authenticated INIT values
InitContext.persistent_directory and InitContext.scratch_directory.
Do not hardcode directory names, including the current host implementation's
/var/lib/flexmodule/data and /var/lib/flexmodule/scratch paths.
ModuleID is an operator-assigned stable installation identity; InstanceID is
fresh per execution. Neither caller metadata nor flexmodule-work-ref creates
identity or grants. During drain, canonical finite Discord REST follow-ups and
finite voice controls/queries require the same authenticated instance's exact
live event-delivery work reference, existing grants and resource scopes, all
within the drain deadline. Missing, foreign or completed-delivery references
cannot authorize them or detached workers. New uploads, playback jobs, streams,
receive subscriptions, route registrations and credential issuance remain
closed even with a live reference. Owner-cleanup operations instead permit
owned route unregistration, job cancellation and unsubscription without a work
reference; their grants, scopes and resource ownership checks still apply.
Typed Discord operations
Construct the ordinary client with discordv2.NewClient(conn). Calls are
context-first and return errors. The SDK includes 153 canonical operations,
43 explicit convenience aliases, and the three route/credential management
operations. Aliases map to canonical RPCs, not additional capabilities.
See operations.go, client_generated.go, aliases.go and the reviewed
api-mapping.json for exact signatures and
dispositions. The host supplies Discord API v10/Gateway transport; the SDK does
not expose a raw HTTP escape hatch or live discordgo.Session/State.
Capabilities are exact operation names, for example
discord.rest.GuildMemberRoleAdd, discord.gateway.RequestGuildMembers, and
discord.event.INTERACTION_CREATE. A namespace prefix is not a wildcard grant.
The host separately checks instance state, actual capability and resource
scopes, trusted relationships, credential purpose/expiry and ownership. Discord
bot permissions, end-user command permissions and Gateway intents still apply;
none replaces a runtime grant.
Complete member-role replacement (GuildMemberEdit with a present roles list,
including empty) checks current plus submitted roles and requires protected
guild-wide authority because Discord cannot fence concurrent role assignments
atomically. An absent roles field is unchanged. Granular GuildMemberRoleAdd
and GuildMemberRoleRemove remain separately scoped operations.
Use the generated safe views and partial/nullable wrappers where the source SDK would lose presence. Absent, explicit zero/false/empty, list clear and JSON null are distinct. Interaction and webhook handles hold opaque credential refs, not raw tokens. Live host objects, voice session credentials and bot tokens do not cross the module boundary.
Typed snapshots remain authoritative for field presence. When an ordinary
absent/value object maps to a nonpointer SDK struct (for example
User.PrimaryGuild or Activity.Assets), an absent snapshot field leaves the SDK
field at its zero value; conversion does not invent a present wire object.
Provider null and omission retain the existing ordinary snapshot normalization;
partial/nullable DTOs retain their explicit null distinction. Optional SDK
pointers stay nil, and null collection elements, malformed objects and invalid
nullable/union variants are still rejected.
Outbound message, webhook and component conversion derives value-only string
omission from the reviewed SDK json:",omitempty" tags. Empty optional source
strings are omitted; nonempty strings are retained. This includes all four
WebhookParams strings (Content, Username, AvatarURL, ThreadName), not
only premium-button SKUID. Ordinary message snapshots and presence-aware
edit/nullable fields do not use this rule.
Five reviewed value-only numeric fields also follow their source zero-omission contract, rather than overriding a provider default with a present zero:
| Source field | Meaning when omitted |
|---|---|
Poll.Duration |
24 hours |
Poll.LayoutType |
DEFAULT layout, value 1 |
SelectMenu.MaxValues, FileUpload.MaxValues |
Maximum count defaults to 1 |
TextInput.MaxLength |
Limit unspecified; a present value must be 1–4000 |
These are source-adaptation rules, not a blanket omitempty encoder. Nonzero
values (including invalid values requiring normal validation), other numeric
zero/false values, pointers, nullable fields and collection presence remain
unchanged. Direct typed wire presence is authoritative: the HTTP encoder does
not silently remove explicitly empty strings or explicit zero values.
Interaction credential scopes retain the authenticated invoking user_id from
guild Member.User or DM User, alongside the source interaction/application
and present guild/channel IDs. Missing or conflicting invoking users fail before
credential issuance. Callback and followup authorization preserve that immutable
user binding; caller-supplied reference metadata cannot replace it.
A returned message's Author identifies that message's author, not the invoking
user. Credential-backed postflight checks retain the authenticated invoker while
validating returned author IDs and all other resource relationships; a bot-authored
response does not require replacing or widening the approved invoking user.
Command create, edit, get, list and bulk-overwrite use ApplicationCommandView,
including ApplicationCommandToProto and ProtoToApplicationCommand. Its
DefaultMemberPermissions is *Nullable[int64]: nil means absent;
&Nullable[int64]{Null: true} means explicit null (permission clear on edit);
&Nullable[int64]{Value: 0} means explicit administrator-only zero; a nonzero
Value retains the exact nonnegative permission mask. HTTP requests emit null,
"0" or the decimal mask string respectively; absence omits the key. A normal
Discord response with default_member_permissions: null therefore remains a
present null, not an error, an omitted permission or administrator-only zero.
Command options, including recursively nested options, use
ApplicationCommandOptionView. Its MaxValue *float64 and MaxLength *int
preserve omission rather than inventing zero limits from SDK value-only fields.
For example, an ordinary string autocomplete option with nil bounds sends neither
max_value nor max_length; MaxValue: new(float64(0)) sends an explicit numeric
upper bound of zero, and MaxLength: new(200) sends a supported string limit.
Other option fields, choices, context/integration lists and optional default
flags retain their SDK-compatible types. There are no discordgo.ApplicationCommand
or discordgo.ApplicationCommandOption compatibility overloads: rebuild and
migrate callers to the views rather than collapsing presence.
File readers are not protobuf fields: explicitly stream with
core.FileClient.Upload and pass owner-bound UploadedFileRef values to typed
Discord operations. Uploads use at most 256 KiB chunks, a separate 500 MiB
storage cap and 30-minute TTL after completion. Discord endpoint limits can be
smaller. Refs can be reused only inside the owning instance and must not be
persisted across restart. Attachment edits specify the complete retained-ID/
new-file-index set; absence and explicit empty clear are different. Helpers do
not silently upload, defer an interaction or retry a mutation.
Optional voice uses NewVoiceClient(conn) and bounded playback/receive jobs,
not OpusSend channels or module-side Discord sessions. The producer observes
frame and maximum-packet byte credit before reading/encoding each 48 kHz/20 ms
Opus frame, explicitly ends input, and waits for an actual terminal result.
Native DAVE belongs to the separately built host voice artifact; FFmpeg and
download tools belong only inside approved media module images.
Examples and maintenance
general-bot: ordinary management, settings, interactions, messages and uploads; buildsbin/test-modulewithout voice/media prerequisites.music-bot: optional queue/provider module with bounded media preparation; buildsbin/chatanium-musicbot.audio-player: optional bounded attachment download/encoding and voice jobs; buildsbin/voice-player-module.../proto/README.md: schema/generator inputs and ordering.../README.md: pinned artifacts, privileged host preparation, private secret bindings, runtime configuration and evidence boundaries.
Go is the maintained SDK implementation. Other languages can generate wire bindings, but must also implement the authenticated sandbox bootstrap, single-helper transport, lifecycle, presence, credential and error contracts; generating messages alone is not a supported module implementation. The protocol remains subject to the linked P0-P6 design/acceptance contracts.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package corev2 implements the backend-neutral FlexModule v2 module SDK.
|
Package corev2 implements the backend-neutral FlexModule v2 module SDK. |
|
Code generated by tools/protocol/generate-conversions.py; DO NOT EDIT.
|
Code generated by tools/protocol/generate-conversions.py; DO NOT EDIT. |
|
media
|
|
|
opus
Package opus provides module-side ffmpeg encoding and bounded Opus frame reading.
|
Package opus provides module-side ffmpeg encoding and bounded Opus frame reading. |