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, one 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.

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.

// EventDirectMessage is "messaging.direct"
type EventDirectMessage struct {
	Recipient datapages.SubjectUser `json:"recipient"`

	Content string `json:"content"`
}

• One dispatch targets one subject. To notify several recipients, dispatch once per recipient. Each publish can fail independently.
• Two events must not share a subject. An event with subject fields also claims every subject below its base subject. For example, "chat" with fields conflicts with "chat.msg".
• A subject value may contain any byte. Datapages escapes bytes that are not valid in a subject, so an email address works. An empty value fails the dispatch and publishes nothing.
• SubjectUser sends only to the client authenticated as that user and requires a session type. An event may have one SubjectUser field: the generator rejects a second one, such as To, Cc datapages.SubjectUser. Validate an ID with datapages.ValidateUserID before returning it in a new session.
• A signal:"name" tag on a datapages.Subject field gets the value from the client signal. An empty value returns 400. Datapages escapes * as a literal segment, not a wildcard. The tag is a period-separated signal path. Each segment must match [A-Za-z_][A-Za-z0-9_]* and must not contain __. Two fields must not use the same signal. A page's events must not need one signal both as a value and as an object, such as chat and chat.room. A SubjectUser field cannot have this tag because it is already bound to the authenticated user.