datapages-events

Events

Read datapages first for the build loop, hard rules and naming conventions. Read datapages-state when the page uses per-tab server state.

A handler dispatches an event type. Datapages delivers it over SSE to subscribed pages. Declare the type in the app package or an imported package. Types in imported packages can be shared by multiple apps.

// EventMessageSent is "messaging.sent"
type EventMessageSent struct {
	Message string `json:"message"`
}

Dispatch

Add a datapages.Dispatcher[EventX] parameter, 1 per event type.

func (PageChat) POSTSend(
	r *http.Request,
	messageSent datapages.Dispatcher[EventMessageSent],
) error {
	return messageSent.Dispatch(EventMessageSent{Message: "hello"})
}

Dispatch uses the handler's context. Use DispatchCtx(ctx, ev) when the publish can outlive the handler or needs a separate deadline. An action can use r.Context(). An On handler has no request and can use sse.Context(). Publishes through multiple dispatchers are not atomic. Combine their errors with errors.Join.

Handle

On + the event name, on a page or on an embedded type.

func (PageChat) OnMessageSent(
	event EventMessageSent,
	sse datapages.SSE,
	streamID datapages.StreamID, // optional
	session Session,             // optional
) error {
	return sse.PatchElement(messageComponent(event.Message))
}

The event and sse are required. On handlers cannot accept signals. Put required data on the event, or use datapages.State[T] for per-tab data.

Datapages logs an error that an On handler returns and keeps the stream open. It does not call RecoverError, so send feedback with sse before returning. A panic reaches RecoverError as a datapages.PanicError and closes the stream.

Subjects

A subject field must have the exact type datapages.Subject or datapages.SubjectUser. The generator rejects a defined type such as type Recipient datapages.SubjectUser, and a field that holds a subject type, such as []datapages.SubjectUser, which would route nothing. Subject fields must be exported and must precede payload fields. Their values extend the base subject in field order, separated by periods. EventDirectMessage{Recipient: "u1"} publishes to messaging.direct.u1. A subject field must not be tagged json:"-": the payload carries its value, the subject only routes the event.