events

type AuthenticateContext ¶ added in v0.6.5

type AuthenticateContext struct {
	InputUsername string
	InputPassword string
	Path          string
	RequireAdmin  bool
	GetHeader     func(key string) string
	// contains filtered or unexported fields
}

AuthenticateContext is passed to authenticate hooks during HTTP authentication, before the built-in basic-auth check. The first callback to answer wins: a callback calls Authenticate(username) to confirm a user or Reject() to fail authentication; calling neither defers to the next callback / built-in basic auth. GetHeader reads a request header by key. InputUsername and InputPassword are the credentials supplied by the client; Username() returns the identity confirmed by the winning Authenticate() call.

func (c *AuthenticateContext) Answered() bool

func (c *AuthenticateContext) Authenticate(username string)

func (c *AuthenticateContext) Reject()

func (c *AuthenticateContext) Rejected() bool

func (c *AuthenticateContext) Username() string

type AuthnFailureContext ¶ added in v0.6.5

type AuthnFailureContext struct {
	Path         string
	RequireAdmin bool
	// contains filtered or unexported fields
}

AuthnFailureContext is passed to authnFailure hooks when authentication fails. A callback can take over the error response (instead of the default 401) by calling Respond (optionally adding headers via SetHeader, e.g. a Location header for a login redirect).

func (c *AuthnFailureContext) Body() string

func (c *AuthnFailureContext) Handled() bool

func (c *AuthnFailureContext) Headers() map[string]string

func (c *AuthnFailureContext) Respond(status int, body string)

func (c *AuthnFailureContext) SetHeader(key, value string)

func (c *AuthnFailureContext) Status() int

type AuthorizeContext ¶ added in v0.6.5

type AuthorizeContext struct {
	Path         string
	PadId        string
	RequireAdmin bool
	User         any
	// contains filtered or unexported fields
}

AuthorizeContext is passed to authorize hooks during post-authentication authorization. A callback may Grant a level ("create"/"modify"/"readOnly") or Deny(). Deny wins over any grant; otherwise the first granted level is used; if no callback answers, the decision defers to the built-in logic. User is the authenticated user (any; plugins type-assert) or nil.

func (c *AuthorizeContext) Decision() AuthorizeDecision

func (c *AuthorizeContext) Deny()

func (c *AuthorizeContext) Grant(level string)

func (c *AuthorizeContext) Level() string

type AuthorizeDecision ¶ added in v0.6.5

type AuthorizeDecision int

AuthorizeDecision is the aggregated answer of all authorize hook callbacks.

const (
	// AuthorizeDefer means no callback answered: fall through to built-in logic.
	AuthorizeDefer AuthorizeDecision = iota
	// AuthorizeGrant means a callback granted access at Level().
	AuthorizeGrant
	// AuthorizeDeny means a callback denied access (wins over any grant).
	AuthorizeDeny
)

type AuthzFailureContext ¶ added in v0.6.5

type AuthzFailureContext struct {
	Path         string
	RequireAdmin bool
	// contains filtered or unexported fields
}

AuthzFailureContext is passed to authzFailure hooks when authorization fails. A callback can take over the error response (instead of the default 403) by calling Respond (optionally adding headers via SetHeader).

func (c *AuthzFailureContext) Body() string

func (c *AuthzFailureContext) Handled() bool

func (c *AuthzFailureContext) Headers() map[string]string

func (c *AuthzFailureContext) Respond(status int, body string)

func (c *AuthzFailureContext) SetHeader(key, value string)

func (c *AuthzFailureContext) Status() int

type ChatNewMessageContext ¶ added in v0.6.5

type ChatNewMessageContext struct {
	Message  any
	Text     *string
	PadId    string
	AuthorId string
	// contains filtered or unexported fields
}

ChatNewMessageContext is passed to chatNewMessage hooks before a chat message is stored and broadcast. To change the text, set *ctx.Text = "..." (the canonical form); reassigning ctx.Text = &newString also works because the fire site reads ctx.Text back after the hooks run. A callback may call DropMessage() to suppress the message entirely. Message is the chat message exposed as `any`.

func (c *ChatNewMessageContext) DropMessage()

func (c *ChatNewMessageContext) Dropped() bool

type ClientReadyContext ¶ added in v0.6.5

type ClientReadyContext struct {
	PadId    string
	AuthorId string
	Token    string
}

ClientReadyContext is passed to clientReady hooks once a client has finished joining a pad (informational).

type ClientVarsContext ¶ added in v0.6.5

type ClientVarsContext struct {
	ClientVars *clientVars.ClientVars
	Extra      map[string]any
	PadId      string
	AuthorId   string
}

ClientVarsContext is passed to clientVars hooks just before the CLIENT_VARS payload is sent. A callback may mutate the typed ClientVars fields and/or add arbitrary top-level keys via Extra. On key collision the typed field wins (Extra cannot clobber engine-owned keys). The fire site is responsible for initializing Extra to a non-nil map before firing this hook.

type ExportFileNameContext ¶ added in v0.6.5

type ExportFileNameContext struct {
	PadId      string
	ReadOnlyId string
	ExportType string
	// contains filtered or unexported fields
}

ExportFileNameContext is passed to exportFileName hooks before the export's download filename is set. First non-empty SetFileName wins. The extension is chosen by core and cannot be overridden (security).

func (c *ExportFileNameContext) FileName() string

func (c *ExportFileNameContext) SetFileName(name string)

type ExportHTMLAdditionalContentContext ¶ added in v0.6.5

type ExportHTMLAdditionalContentContext struct {
	PadId string
	// contains filtered or unexported fields
}

ExportHTMLAdditionalContentContext is passed to exportHTMLAdditionalContent hooks during HTML export. Each Add appends HTML to the exported body.

func (c *ExportHTMLAdditionalContentContext) Add(html string)

func (c *ExportHTMLAdditionalContentContext) Content() string

type ExportHTMLSendContext ¶ added in v0.6.5

type ExportHTMLSendContext struct {
	PadId string
	HTML  *string
}

ExportHTMLSendContext is passed to exportHTMLSend hooks just before the HTML export response is sent. A callback may replace the document via *ctx.HTML; the caller reads HTML back after the hooks run.

type GetAuthorIdContext ¶ added in v0.6.5

type GetAuthorIdContext struct {
	Token string
	User  any
	// contains filtered or unexported fields
}

GetAuthorIdContext is passed to getAuthorId hooks to let a plugin supply or override the author id resolved from a token. First non-empty answer wins; if none answer, the caller falls back to the database token->author mapping. User is the authenticated user (exposed as any; plugins type-assert) or nil.

func (c *GetAuthorIdContext) AuthorId() string

func (c *GetAuthorIdContext) SetAuthorId(id string)

type HandleMessageContext ¶ added in v0.6.5

type HandleMessageContext struct {
	Message  any
	Client   any
	PadId    string
	AuthorId string
	// contains filtered or unexported fields
}

HandleMessageContext is passed to handleMessage hooks before an incoming socket message is dispatched. Message and Client are exposed as `any` to avoid the lib/ws -> lib/hooks import cycle; plugins type-assert them (Message to a concrete ws message type, Client to *ws.Client). A callback may call DropMessage() to stop the message from being processed.

func (c *HandleMessageContext) DropMessage()

func (c *HandleMessageContext) Dropped() bool

type HandleMessageSecurityContext ¶ added in v0.6.5

type HandleMessageSecurityContext struct {
	Message  any
	PadId    string
	AuthorId string
	// contains filtered or unexported fields
}

HandleMessageSecurityContext is passed to handleMessageSecurity hooks when a write message arrives on a read-only connection. A callback may call GrantWriteAccess() to allow this single message through. Message is `any`.

func (c *HandleMessageSecurityContext) GrantWriteAccess()

func (c *HandleMessageSecurityContext) WriteAccessGranted() bool

type ImportContext ¶ added in v0.6.5

type ImportContext struct {
	FileEnding string
	PadId      string
	AuthorId   string
	Content    []byte
	// contains filtered or unexported fields
}

ImportContext is passed to import hooks before the built-in file-extension dispatch. A plugin handling a (custom) format either fully handles it and calls Handle(), or hands back converted content via SetHTML/SetText (which also marks it handled) for core to import. If no callback handles it, the built-in importer runs. Content is the raw uploaded bytes.

func (c *ImportContext) HTML() (string, bool)

func (c *ImportContext) Handle()

func (c *ImportContext) Handled() bool

func (c *ImportContext) SetHTML(html string)

func (c *ImportContext) SetText(text string)

func (c *ImportContext) Text() (string, bool)

type ImportEtherpadContext ¶ added in v0.6.5

type ImportEtherpadContext struct {
	PadId    string
	SrcPadId string
	Data     map[string]any
}

ImportEtherpadContext is passed to importEtherpad hooks after a .etherpad file is parsed, before its records are persisted. Data is the parsed top-level JSON object; plugins may inspect or augment it. (lite's prefix-based extra-record / temporary pad.db model is intentionally not ported.)

type LineDocxForExportContext ¶

type LineDocxForExportContext struct {
	Line        *models.LineModel
	LineContent *string
	Apool       *apool.APool
	AttribLine  *string
	Text        *string
	PadId       *string
	Alignment   *string // "left", "center", "right", "justify"
	Heading     *string // e.g., "Heading1", "Normal", etc. -> word styles
}

LineDocxForExportContext is the context for the getLineDocxForExport hook

type LineHtmlForExportContext ¶

type LineHtmlForExportContext struct {
	Line        *models.LineModel
	LineContent *string
	Apool       *apool.APool
	AttribLine  *string
	Text        *string
	PadId       *string
}

type LineMarkdownForExportContext ¶ added in v0.0.5

type LineMarkdownForExportContext struct {
	Apool      *apool.APool
	AttribLine *string
	Text       *string
	PadId      *string
	Heading    *string // "h1", "h2", etc.
}

type LineOdtForExportContext ¶

type LineOdtForExportContext struct {
	Line         *models.LineModel
	LineContent  *string
	Apool        *apool.APool
	AttribLine   *string
	Text         *string
	PadId        *string
	Alignment    *string // "left", "center", "right", "justify"
	IsHeading    *bool
	OutlineLevel *int
	Heading      *string // e.g., "Heading 1", "Text Body", etc. -> odt styles
}

LineOdtForExportContext is the context for the getLineOdtForExport hook

type LinePDFForExportContext ¶

type LinePDFForExportContext struct {
	Line        *models.LineModel
	LineContent *string
	Apool       *apool.APool
	AttribLine  *string
	Text        *string
	PadId       *string
	Alignment   *string // "left", "center", "right", "justify"
	FontSize    *float64
	Bold        *bool
	Heading     *string // e.g., "h1", "h2", etc.
}

LinePDFForExportContext is the context for the getLinePDFForExport hook

type LineTxtForExportContext ¶

type LineTxtForExportContext struct {
	Line        *models.LineModel
	LineContent *string
	Apool       *apool.APool
	AttribLine  *string
	Text        *string
	PadId       *string
}

LineTxtForExportContext is the context for the getLineTxtForExport hook

type LoadSettingsContext ¶ added in v0.6.5

type LoadSettingsContext struct {
	Settings any
}

LoadSettingsContext is passed to loadSettings hooks once settings are loaded and plugins have registered (server startup). Settings is exposed as any to avoid an events->settings import cycle; plugins type-assert to *settings.Settings.

type LocaleLoadContext ¶

type LocaleLoadContext struct {
	RequestedLocale    string
	LoadedTranslations map[string]string
}

type OnAccessCheckContext ¶ added in v0.6.5

type OnAccessCheckContext struct {
	PadId         string
	Token         string
	SessionCookie string
	// contains filtered or unexported fields
}

OnAccessCheckContext is passed to onAccessCheck hooks when access to a concrete pad is being checked (socket pad access). Mirrors the original's "any false denies" semantics: a single Deny() denies access.

func (c *OnAccessCheckContext) Denied() bool

func (c *OnAccessCheckContext) Deny()

type PadCopyContext ¶ added in v0.6.5

type PadCopyContext struct {
	SrcPad any
	DstPad any
	SrcId  string
	DstId  string
}

PadCopyContext is passed to the padCopy hook after a pad is copied to a new destination (copyPad, copyPadWithoutHistory, movePad).

type PadCreateContext ¶ added in v0.6.5

type PadCreateContext struct {
	Pad   any
	PadId string
	// AuthorId is the creating author; empty string when the pad is created
	// without a known author (e.g. server-side operations). Unlike
	// PadDefaultContentContext.AuthorId this is a plain string, not a pointer.
	AuthorId string
}

PadCreateContext is passed to the padCreate hook right after a pad's first revision is persisted.

type PadDefaultContentContext ¶ added in v0.6.5

type PadDefaultContentContext struct {
	Type     *string
	Content  *string
	Pad      any
	AuthorId *string
	PadId    string
}

PadDefaultContentContext is passed to the padDefaultContent hook before a new pad's initial revision is written. A callback may replace Content (and Type); the caller reads Content back after the hook runs.

type PadLoadContext ¶ added in v0.6.5

type PadLoadContext struct {
	Pad   any
	PadId string
}

PadLoadContext is passed to the padLoad hook whenever a pad is materialized.

type PadRemoveContext ¶ added in v0.6.5

type PadRemoveContext struct {
	Pad   any
	PadId string
}

PadRemoveContext is passed to the padRemove hook when a pad is deleted.

type PadUpdateContext ¶ added in v0.6.5

type PadUpdateContext struct {
	Pad      any
	PadId    string
	AuthorId string
	// Revs is the pad's new head revision number after this update.
	Revs      int
	Changeset string
}

PadUpdateContext is passed to the padUpdate hook after a revision is appended.

type PreAuthorizeContext ¶ added in v0.6.3

type PreAuthorizeContext struct {
	// Path is the request path, e.g. "/p/mypad" (input, read-only).
	Path string
	// RequireAdmin is true when the request is for an /admin-auth page (input,
	// read-only).
	RequireAdmin bool
	// contains filtered or unexported fields
}

PreAuthorizeContext is passed to preAuthorize hook callbacks. It is the Go counterpart of the original hook context {req, res, next}: callbacks inspect Path/RequireAdmin and answer by calling Permit or Deny; calling neither defers to the regular authenticate/authorize steps. The classic use case is permitting static resource paths so they skip authentication.

Semantics adapted from the original's hooks.aCallFirst: the Go hook system runs every registered callback (in unspecified order) instead of stopping at the first one that answers, so a single Deny always wins over any number of Permits. As in the original, Permits on /admin-auth pages (RequireAdmin) are filtered out so plugins cannot accidentally grant admin privileges to the general public.

func (c *PreAuthorizeContext) Decision() PreAuthorizeDecision

func (c *PreAuthorizeContext) Deny()

func (c *PreAuthorizeContext) Permit()

type PreAuthorizeDecision ¶ added in v0.6.3

type PreAuthorizeDecision int

PreAuthorizeDecision is the aggregated answer of all preAuthorize hook callbacks for a request.

const (
	// PreAuthorizeDefer means no callback answered: fall through to the regular
	// authenticate/authorize steps (the original's empty result list).
	PreAuthorizeDefer PreAuthorizeDecision = iota
	// PreAuthorizePermit means access was explicitly granted: skip the remaining
	// steps (the original's `return next()` when every result is truthy).
	PreAuthorizePermit
	// PreAuthorizeDeny means access was explicitly denied: respond with 403
	// unless a preAuthzFailure callback overrides the response.
	PreAuthorizeDeny
)

type PreAuthzFailureContext ¶ added in v0.6.3

type PreAuthzFailureContext struct {
	// Path is the request path (input, read-only).
	Path string
	// RequireAdmin is true when the request is for an /admin-auth page (input,
	// read-only).
	RequireAdmin bool
	// contains filtered or unexported fields
}

PreAuthzFailureContext is passed to preAuthzFailure hook callbacks when a preAuthorize callback denied access. A callback can take over the error response — the original's "return truthy after writing to res" — by calling Respond (optionally adding headers via SetHeader, e.g. a Location header for a login redirect). If no callback responds, the default 403 Forbidden is sent.

func (c *PreAuthzFailureContext) Body() string

func (c *PreAuthzFailureContext) Handled() bool

func (c *PreAuthzFailureContext) Headers() map[string]string

func (c *PreAuthzFailureContext) Respond(status int, body string)

func (c *PreAuthzFailureContext) SetHeader(key, value string)

func (c *PreAuthzFailureContext) Status() int

type ShutdownContext ¶ added in v0.6.5

type ShutdownContext struct{}

ShutdownContext is passed to shutdown hooks during graceful shutdown. The database may be unavailable; callbacks must return quickly.

type StylesForExportContext ¶ added in v0.6.5

type StylesForExportContext struct {
	PadId string
	// contains filtered or unexported fields
}

StylesForExportContext is passed to stylesForExport hooks during HTML export. Each AddStyle appends CSS; all are concatenated into the document <style>.

func (c *StylesForExportContext) AddStyle(css string)

func (c *StylesForExportContext) Styles() string

type UserJoinLeaveContext ¶ added in v0.5.0

type UserJoinLeaveContext struct {
	PadId    string
	AuthorId string
	// BroadcastChat sends a chat message to all clients in the pad room without persisting it.
	// The message map is serialized as the "message" field inside a CHAT_MESSAGE COLLABROOM event.
	BroadcastChat func(message map[string]any)
}

UserJoinLeaveContext is passed to userJoin and userLeave hooks.