Documentation
¶
Overview ¶
Package hook is the extension bus every module — and later every plugin — uses.
Three kinds of hooks:
- Guard: synchronous, may reject an action with a reason (auth.register, texture.upload…)
- Filter: synchronous, rewrites a value (player.name, user.badges…)
- Event: asynchronous notification after the fact (texture.uploaded…). Domain events are published inside the transaction of the change (Event.Publish) and delivered after it commits, at least once, through the job queue (the outbox).
Hooks are declared once with a typed payload (NewGuard / NewFilter / NewEvent); the declarations form the catalog that docs and the plugin SDK types are generated from. Handlers are registered per owner ("core", "module:yggdrasil", "plugin:invitation-codes") and an owner's handlers are swapped atomically, which is how hot reload works.
Index ¶
- Constants
- Variables
- func DeclarePluginEvent(name string)
- func DeliveryKey(ctx context.Context) string
- func EmitDynamic(b *Bus, name string, payload any)
- func RedactForm(form map[string]any) map[string]any
- func Reject(reason string) error
- type AuthLoginGuard
- type AuthRegisterGuard
- type Bus
- type CheckinFilterContext
- type ClosetAddGuard
- type ClosetEvent
- type ClosetNameFilterContext
- type ClosetRemoveGuard
- type ClosetRenameGuard
- type Def
- type Event
- type FailPolicy
- type Filter
- type Guard
- type Kind
- type PlayerCreateGuard
- type PlayerDeleteGuard
- type PlayerEvent
- type PlayerNameFilterContext
- type PlayerRenameGuard
- type PlayerTexturesClearGuard
- type PlayerTexturesSetGuard
- type ProfileTextures
- type ProfileTexturesFilterContext
- type Registration
- func HandleEventDynamic(name string, order int, fn func(ctx context.Context, payload any) error) (Registration, error)
- func HandleFilterDynamic(name string, order int, ...) (Registration, error)
- func HandleGuardDynamic(name string, order int, fn func(ctx context.Context, payload any) error) (Registration, error)
- type Rejection
- type ReportEvent
- type ReportSubmitGuard
- type ScoreChangedEvent
- type ScoreCheckinGuard
- type SettingsChanged
- type TextureDeleteGuard
- type TextureEvent
- type TextureNameFilterContext
- type TextureRenameGuard
- type TextureTypeGuard
- type TextureUploadGuard
- type TextureVisibilityGuard
- type UserAvatarUpdateGuard
- type UserBadge
- type UserBadgeFilterContext
- type UserEvent
- type UserLoginEvent
- type UserProfileUpdateGuard
- type UserUpdatedEvent
- type YggPropertiesFilterContext
- type YggProperty
- type YggdrasilAuthGuard
- type YggdrasilJoinGuard
- type YggdrasilJoinedEvent
Constants ¶
const OutboxJobKind = "hook.event"
OutboxJobKind is the job that delivers a published event (Event.Publish).
Variables ¶
var ( OnUserRegistered = NewEvent[UserEvent]("user.registered", 1, "An account was created.") OnUserLoggedIn = NewEvent[UserLoginEvent]("user.loggedIn", 1, "A user logged in.") OnUserUpdated = NewEvent[UserUpdatedEvent]("user.updated", 1, "An account's fields were updated.") OnUserBanned = NewEvent[UserEvent]("user.banned", 1, "An administrator banned an account.") OnUserDeleted = NewEvent[UserEvent]("user.deleted", 1, "An account was removed for good (an administrator's delete, or the end of the grace period after the user deleted it). Its players (each announced as player.deleted first), closet and private textures went with it; its public textures stay without an uploader.") OnScoreChanged = NewEvent[ScoreChangedEvent]("score.changed", 1, "A user's score changed via the ledger.") OnYggdrasilJoined = NewEvent[YggdrasilJoinedEvent]("yggdrasil.joined", 1, "A player joined a game server via Yggdrasil sessionserver.") )
var ( OnPlayerCreated = NewEvent[PlayerEvent]("player.created", 1, "A player was created.") OnPlayerRenamed = NewEvent[PlayerEvent]("player.renamed", 1, "A player was renamed (with v3 UUIDs its UUID changed with the name).") OnPlayerUpdated = NewEvent[PlayerEvent]("player.updated", 1, "What a player wears changed (put on, taken off, or removed with a texture or a closet item), or its owner's account was banned, deleted or restored: what game clients get for it is different now.") OnPlayerDeleted = NewEvent[PlayerEvent]("player.deleted", 1, "A player was deleted by its owner or an administrator, or with its account.") )
var ( OnTextureUploaded = NewEvent[TextureEvent]("texture.uploaded", 1, "A texture was uploaded (not sent for a duplicate upload).") OnTextureUpdated = NewEvent[TextureEvent]("texture.updated", 1, "A texture's name, type or visibility changed.") OnTextureDeleted = NewEvent[TextureEvent]("texture.deleted", 1, "A texture was deleted (by its uploader, an administrator, a report review, or with its uploader's account).") )
var ( OnClosetAdded = NewEvent[ClosetEvent]("closet.added", 1, "A texture was added to a closet (by its owner, an upload, or an administrator).") OnClosetRemoved = NewEvent[ClosetEvent]("closet.removed", 1, "A texture left a closet (removed, or taken out when it went private or was deleted). Not sent for closets deleted with their account.") )
var ( OnReportSubmitted = NewEvent[ReportEvent]("report.submitted", 1, "A user reported a texture.") OnReportResolved = NewEvent[ReportEvent]("report.resolved", 1, "An administrator reviewed a report (resolved or rejected); other pending reports a texture deletion settled are sent too.") )
var ( GuardAuthLogin = NewGuard[AuthLoginGuard]("auth.login", 1, FailClosed, "Guard checked before completing password login.") GuardAuthRegister = NewGuard[AuthRegisterGuard]("auth.register", 1, FailClosed, "Guard checked before registering an account.") GuardPlayerCreate = NewGuard[PlayerCreateGuard]("player.create", 1, FailClosed, "Guard checked before creating a player.") GuardPlayerRename = NewGuard[PlayerRenameGuard]("player.rename", 1, FailClosed, "Guard checked before renaming a player.") GuardPlayerDelete = NewGuard[PlayerDeleteGuard]("player.delete", 1, FailClosed, "Guard checked before deleting a player.") GuardPlayerTexturesSet = NewGuard[PlayerTexturesSetGuard]("player.textures.set", 1, FailClosed, "Guard checked before setting player textures.") GuardPlayerTexturesClear = NewGuard[PlayerTexturesClearGuard]("player.textures.clear", 1, FailClosed, "Guard checked before clearing player textures.") GuardTextureUpload = NewGuard[TextureUploadGuard]("texture.upload", 1, FailClosed, "Guard checked before persisting an uploaded texture.") GuardTextureRename = NewGuard[TextureRenameGuard]("texture.rename", 1, FailClosed, "Guard checked before renaming a texture.") GuardTextureVisibility = NewGuard[TextureVisibilityGuard]("texture.visibility", 1, FailClosed, "Guard checked before changing texture visibility.") GuardTextureType = NewGuard[TextureTypeGuard]("texture.type", 1, FailClosed, "Guard checked before changing a texture's model type.") GuardTextureDelete = NewGuard[TextureDeleteGuard]("texture.delete", 1, FailClosed, "Guard checked before deleting a texture.") GuardClosetAdd = NewGuard[ClosetAddGuard]("closet.add", 1, FailClosed, "Guard checked before adding a texture to a closet.") GuardClosetRename = NewGuard[ClosetRenameGuard]("closet.rename", 1, FailClosed, "Guard checked before renaming a closet item.") GuardClosetRemove = NewGuard[ClosetRemoveGuard]("closet.remove", 1, FailClosed, "Guard checked before removing a closet item.") GuardScoreCheckin = NewGuard[ScoreCheckinGuard]("score.checkin", 1, FailClosed, "Guard checked before awarding a daily check-in.") GuardUserProfileUpdate = NewGuard[UserProfileUpdateGuard]("user.profile.update", 1, FailClosed, "Guard checked before updating profile fields.") GuardUserAvatarUpdate = NewGuard[UserAvatarUpdateGuard]("user.avatar.update", 1, FailClosed, "Guard checked before updating a user's avatar.") GuardReportSubmit = NewGuard[ReportSubmitGuard]("report.submit", 1, FailClosed, "Guard checked before recording a texture report.") GuardYggdrasilAuthenticate = NewGuard[YggdrasilAuthGuard]("yggdrasil.authenticate", 1, FailOpen, "Guard checked before issuing a Yggdrasil token.") GuardYggdrasilJoin = NewGuard[YggdrasilJoinGuard]("yggdrasil.join", 1, FailOpen, "Guard checked before recording a Yggdrasil server join.") )
var ( FilterPlayerName = NewFilter[string, PlayerNameFilterContext]("player.name", 1, "Filters a player name before validation on create or rename.") FilterTextureName = NewFilter[string, TextureNameFilterContext]("texture.name", 1, "Filters a texture name on upload or rename.") FilterClosetItemName = NewFilter[string, ClosetNameFilterContext]("closet.itemName", 1, "Filters a closet item name on add or rename.") FilterScoreCheckinAmount = NewFilter[int64, CheckinFilterContext]("score.checkinAmount", 1, "Filters the daily check-in score reward before granting.") FilterUserBadges = NewFilter[[]UserBadge, UserBadgeFilterContext]("user.badges", 1, "Filters custom user badges shown in profile, texture uploader and admin views.") FilterProfileTextures = NewFilter[ProfileTextures, ProfileTexturesFilterContext]("profile.textures", 1, "Filters resolved textures for CSL, USM, or Yggdrasil profiles.") FilterYggdrasilProfileProperties = NewFilter[[]YggProperty, YggPropertiesFilterContext]("yggdrasil.profileProperties", 1, "Filters Yggdrasil sessionserver profile properties before returning.") )
var ErrHookFailed = errors.New("hook handler failed")
ErrHookFailed wraps handler failures surfaced by fail-closed guards.
var OnSettingsChanged = NewEvent[SettingsChanged]("settings.changed", 1,
"Runtime settings were saved; payload lists the changed keys.")
OnSettingsChanged fires after a settings write is committed and the new snapshot is live.
Functions ¶
func DeclarePluginEvent ¶ added in v1.1.0
func DeclarePluginEvent(name string)
DeclarePluginEvent registers a plugin-defined event ("plugin:<id>.<name>") idempotently so plugins can emit and subscribe to custom cross-plugin events.
func DeliveryKey ¶
DeliveryKey identifies the delivery of a published event to its handlers; a retry of the same event has the same key ("" outside a delivery).
func EmitDynamic ¶ added in v1.1.0
EmitDynamic asynchronously emits a plugin-defined event to subscribed listeners.
func RedactForm ¶ added in v1.1.0
RedactForm clones form while dropping sensitive credential fields (passwords, passphrases, secrets) so extension fields like invite_code remain available to user.registered listeners without leaking credentials to the outbox or plugins.
Types ¶
type AuthLoginGuard ¶ added in v1.1.0
type AuthRegisterGuard ¶ added in v1.1.0
type Bus ¶
type Bus struct {
// contains filtered or unexported fields
}
Bus dispatches hooks to registered handlers.
func (*Bus) Deliver ¶
Deliver is the job handler for OutboxJobKind. It runs the handlers registered now, in order; if any fails, the job is retried and every handler runs again (hence at least once).
type CheckinFilterContext ¶ added in v1.1.0
type ClosetAddGuard ¶ added in v1.1.0
type ClosetEvent ¶
ClosetEvent is about one closet item.
type ClosetNameFilterContext ¶ added in v1.1.0
type ClosetRemoveGuard ¶ added in v1.1.0
type ClosetRenameGuard ¶ added in v1.1.0
type Def ¶
type Def struct {
Kind Kind
Name string
Version int
Fail FailPolicy // guards only
Timeout time.Duration // per handler call
Payload reflect.Type
Value reflect.Type // filters only
Doc string
}
Def describes one hook in the catalog.
type Event ¶
type Event[P any] struct { // contains filtered or unexported fields }
Event is a typed asynchronous hook.
func (Event[P]) Emit ¶
Emit queues p for every handler registered at the time of the call, in process and best-effort: for process-local notices (settings.changed reaches each node through its own reload). Changes to data use Publish.
func (Event[P]) Listening ¶
Listening reports whether a handler is registered for the event now: a publisher can skip gathering a payload nobody will get.
func (Event[P]) Publish ¶
Publish records p, inside tx (the transaction of the change), for delivery once tx commits: the job queue's table is the outbox, so the event exists exactly when the change does. Delivery is at least once (handlers see DeliveryKey to recognise a repeat) and in no particular order across events. Nothing is stored when no handler is registered at the time of the call, as with Emit, so events nobody listens to cost nothing; a nil bus publishes nothing.
type FailPolicy ¶
type FailPolicy string
FailPolicy decides what a Guard does when a handler errors or times out (as opposed to rejecting on purpose).
const ( // FailOpen logs the failure and lets the action continue. FailOpen FailPolicy = "open" // FailClosed blocks the action with an internal error. FailClosed FailPolicy = "closed" )
type Filter ¶
type Filter[V, P any] struct { // contains filtered or unexported fields }
Filter is a typed filter hook rewriting a V given payload P.
type Guard ¶
type Guard[P any] struct { // contains filtered or unexported fields }
Guard is a typed guard hook.
type PlayerCreateGuard ¶ added in v1.1.0
type PlayerDeleteGuard ¶ added in v1.1.0
type PlayerEvent ¶
type PlayerEvent struct {
PlayerID int64 `json:"playerId"`
UserID int64 `json:"userId"` // the owner
Name string `json:"name"`
UUID string `json:"uuid"`
OldName string `json:"oldName,omitempty"` // player.renamed
}
PlayerEvent is about one player, as it is after the change.
type PlayerNameFilterContext ¶ added in v1.1.0
type PlayerRenameGuard ¶ added in v1.1.0
type PlayerTexturesClearGuard ¶ added in v1.1.0
type PlayerTexturesSetGuard ¶ added in v1.1.0
type ProfileTextures ¶ added in v1.1.0
type ProfileTexturesFilterContext ¶ added in v1.1.0
type Registration ¶
type Registration struct {
// contains filtered or unexported fields
}
Registration is one handler, built by Guard.Handle / Filter.Handle / Event.Handle and installed with Bus.Replace.
func HandleEventDynamic ¶ added in v1.1.0
func HandleEventDynamic(name string, order int, fn func(ctx context.Context, payload any) error) (Registration, error)
HandleEventDynamic builds a Registration for a catalog or plugin-defined event by name.
func HandleFilterDynamic ¶ added in v1.1.0
func HandleFilterDynamic(name string, order int, fn func(ctx context.Context, value, payload any) (any, error)) (Registration, error)
HandleFilterDynamic builds a Registration for a catalog filter by name.
func HandleGuardDynamic ¶ added in v1.1.0
func HandleGuardDynamic(name string, order int, fn func(ctx context.Context, payload any) error) (Registration, error)
HandleGuardDynamic builds a Registration for a catalog guard by name.
type Rejection ¶
Rejection is returned by a Guard handler to refuse an action on purpose.
func AsRejection ¶
AsRejection reports whether err is (or wraps) a Rejection.
type ReportEvent ¶
type ReportEvent struct {
ReportID int64 `json:"reportId"`
TextureID *int64 `json:"textureId,omitempty"`
Status string `json:"status"` // pending | resolved | rejected
Action string `json:"action,omitempty"` // report.resolved: delete | ban | reject
}
ReportEvent is about one report.
type ReportSubmitGuard ¶ added in v1.1.0
type ScoreChangedEvent ¶ added in v1.1.0
type ScoreChangedEvent struct {
UserID int64 `json:"userId"`
Delta int64 `json:"delta"`
BalanceAfter int64 `json:"balanceAfter"`
Reason string `json:"reason"`
}
ScoreChangedEvent is emitted whenever a user's score ledger changes.
type ScoreCheckinGuard ¶ added in v1.1.0
type ScoreCheckinGuard struct {
UserID int64 `json:"userId"`
}
type SettingsChanged ¶
SettingsChanged is emitted after runtime settings were saved.
type TextureDeleteGuard ¶ added in v1.1.0
type TextureEvent ¶
type TextureEvent struct {
TextureID int64 `json:"textureId"`
UploaderID *int64 `json:"uploaderId,omitempty"`
Hash string `json:"hash"`
Type string `json:"type"` // steve | alex | cape
Public bool `json:"public"`
}
TextureEvent is about one texture, as it is after the change (texture.deleted: as it was).
type TextureNameFilterContext ¶ added in v1.1.0
type TextureRenameGuard ¶ added in v1.1.0
type TextureTypeGuard ¶ added in v1.1.0
type TextureUploadGuard ¶ added in v1.1.0
type TextureUploadGuard struct {
UserID int64 `json:"userId"`
Name string `json:"name"`
Type string `json:"type"`
Public bool `json:"public"`
Width int `json:"width"`
Height int `json:"height"`
SizeBytes int64 `json:"sizeBytes"`
Hash string `json:"hash"`
Form map[string]any `json:"form,omitempty"`
}
type TextureVisibilityGuard ¶ added in v1.1.0
type UserAvatarUpdateGuard ¶ added in v1.1.0
type UserBadgeFilterContext ¶ added in v1.1.0
type UserEvent ¶
type UserEvent struct {
UserID int64 `json:"userId"`
// Method is how a new account was created (user.registered): "password",
// "setup" (the first administrator) or "social:<provider id>".
Method string `json:"method,omitempty"`
// Form carries non-sensitive plugin extension fields from registration.
Form map[string]any `json:"form,omitempty"`
}
UserEvent is about one account.
type UserLoginEvent ¶ added in v1.1.0
type UserLoginEvent struct {
UserID int64 `json:"userId"`
IP string `json:"ip,omitempty"`
Method string `json:"method"` // password | social:<id> | ...
}
UserLoginEvent is emitted when an account signs in.
type UserProfileUpdateGuard ¶ added in v1.1.0
type UserUpdatedEvent ¶ added in v1.1.0
UserUpdatedEvent is emitted when account fields change.
type YggPropertiesFilterContext ¶ added in v1.1.0
type YggProperty ¶ added in v1.1.0
type YggdrasilAuthGuard ¶ added in v1.1.0
type YggdrasilJoinGuard ¶ added in v1.1.0
type YggdrasilJoinedEvent ¶ added in v1.1.0
type YggdrasilJoinedEvent struct {
UserID int64 `json:"userId"`
PlayerID int64 `json:"playerId"`
UUID string `json:"uuid"`
ServerID string `json:"serverId"`
IP string `json:"ip,omitempty"`
}
YggdrasilJoinedEvent is emitted after a client finishes a Yggdrasil session join.