turbostreams

package
v0.5.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 11, 2023 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package turbostreams provides server-side support for sending Hotwired Turbo Streams in POST responses as well as over Action Cable.

Index

Constants

View Source 
const (
	MethodPub   = pubsub.MethodPub
	MethodSub   = pubsub.MethodSub
	MethodUnsub = pubsub.MethodUnsub
	MethodMsg   = "MSG"
)

Turbo Streams pub-sub broker event methods.

View Source 
const ChannelName = "Turbo::StreamsChannel"

ChannelName is the name of the Action Cable channel for Turbo Streams.

View Source 
const ContentType = "text/vnd.turbo-stream.html"

ContentType is the MIME type of form submissions for Turbo Stream responses.

Variables

View Source 
var Template string

Template is a Go HTTP template string for rendering Message instances as HTML.

Functions

func Accepted 

func Accepted(h http.Header) bool

Accepted checks the http.Header's ContentType to determine whether to accept it as a Turbo Streams form submission.

func EmptyHandler 

func EmptyHandler(c *Context) error

EmptyHandler is a handler which does nothing.

func NewChannelFactory added in v0.4.0 

func NewChannelFactory(
	b *Broker, sessionID string, checkers ...actioncable.IdentifierChecker,
) actioncable.ChannelFactory

NewChannelFactory creates an actioncable.ChannelFactory for Turbo Streams to create channels for different Turbo Streams streams as needed.

Types

type Action 

type Action string

Action is the Turbo Stream action. 

const (
	ActionAppend  Action = "append"
	ActionPrepend Action = "prepend"
	ActionReplace Action = "replace"
	ActionUpdate  Action = "update"
	ActionRemove  Action = "remove"
	ActionBefore  Action = "before"
	ActionAfter   Action = "after"
)

Standard Turbo Stream actions.

type Broker 

type Broker struct {
	// contains filtered or unexported fields
}

Broker is the pub-sub framework for routing Turbo Streams pub-sub events to handlers. Analogous to Echo's Echo.

func NewBroker 

func NewBroker(logger pubsub.Logger) *Broker

NewBroker creates an instance of Broker.

func (*Broker) Hub 

func (b *Broker) Hub() *Hub

Hub returns the associated pub-sub Hub.

func (*Broker) MSG 

func (b *Broker) MSG(streamName string, h HandlerFunc, m ...MiddlewareFunc) *Route

MSG registers a new MSG route for a stream name with matching handler in the router, with optional route-level middleware. Refer to Broker.Subscribe for details on how SUB handlers are used.

func (*Broker) PUB 

func (b *Broker) PUB(streamName string, h HandlerFunc, m ...MiddlewareFunc) *Route

PUB registers a new PUB route for a stream name with matching handler in the router, with optional route-level middleware. Refer to Broker.Serve for details on how PUB handlers are used.

func (*Broker) SUB 

func (b *Broker) SUB(streamName string, h HandlerFunc, m ...MiddlewareFunc) *Route

SUB registers a new SUB route for a stream name with matching handler in the router, with optional route-level middleware. Refer to Broker.Subscribe for details on how SUB handlers are used.

func (*Broker) Serve 

func (b *Broker) Serve(ctx context.Context) error

Serve launches and cancels PUB handlers based on the appearance and disappearance of subscriptions for the PUB handlers' corresponding stream names. The PUB handler for a stream name is started in a goroutine when a new subscription is added to the broker (or to the broker's Hub) on a stream name which previously did not have associated subscriptions; and its context is canceled upon removal of the only remaining subscription for the stream name. This way, exactly one instance of the PUB handler for a stream name is run exactly when there is at least one subscriber on that stream name. The Broker should not be used after the Serve method finishes running.

func (*Broker) Subscribe added in v0.4.0 

func (b *Broker) Subscribe(
	ctx context.Context, streamName, sessionID string,
	msgConsumer func(ctx context.Context, rendered string) error,
) (finished <-chan struct{})

Subscribe runs the SUB handler for the stream name and, if it does not produce an error, adds a subscription to the broker's Hub with a callback function to handle messages broadcast over the broker's Hub. When the context is canceled, the UNSUB handler is run. Any messages published on the broker's Hub (e.g. messages broadcast from [Context.Publish], [Context.Broadcast], or [Hub.Broadcast]) will be routed to the MSG handler and exposed via Context.Published; the handler should render the messages into Turbo Streams HTML messages and write the result to Context.MsgWriter. The resulting message will then be passed to the message consumer callback function.

func (*Broker) UNSUB 

func (b *Broker) UNSUB(streamName string, h HandlerFunc, m ...MiddlewareFunc) *Route

UNSUB registers a new UNSUB route for a stream name with matching handler in the router, with optional route-level middleware. Refer to Broker.Subscribe for details on how UNSUB handlers are used.

func (*Broker) Use 

func (b *Broker) Use(middleware ...MiddlewareFunc)

Use adds middleware to the chain which is run after the router. Analogous to Echo's Echo.Use.

type BrokerContext added in v0.5.1 

type BrokerContext = pubsub.BrokerContext[*Context, Message]

type Channel 

type Channel struct {
	// contains filtered or unexported fields
}

Channel represents an Action Cable channel for a Turbo Streams stream.

func NewChannel 

func NewChannel(
	identifier string, h *pubsub.Hub[[]Message], subscriber subscriber, sessionID string,
	checkers []actioncable.IdentifierChecker,
) (*Channel, error)

NewChannel checks the identifier with the specified checkers and returns a new Channel instance.

func (*Channel) Perform 

func (c *Channel) Perform(data string) error

Perform handles an Action Cable action command from the client.

func (*Channel) Subscribe 

func (c *Channel) Subscribe(ctx context.Context, sub *actioncable.Subscription) error

Subscribe handles an Action Cable subscribe command from the client with the provided actioncable.Subscription.

type Context 

type Context struct {
	*BrokerContext
	// contains filtered or unexported fields
}

Context represents the context of the current Turbo Streams pub-sub broker event.

func (*Context) MsgWriter 

func (c *Context) MsgWriter() io.Writer

MsgWriter returns an io.Writer to write rendered messages to. Only valid for MSG handlers.

func (*Context) Published 

func (c *Context) Published() []Message

Published returns the messages to be rendered. Only valid for MSG handlers.

func (*Context) SessionID 

func (c *Context) SessionID() string

SessionID returns the ID of the cookie session associated with the HTTP request which created the connection to the client for Turbo Streams. Only valid for SUB, UNSUB, and MSG handlers.

type HandlerFunc 

type HandlerFunc = pubsub.HandlerFunc[*Context]

HandlerFunc defines a function to handle Turbo Streams pub-sub events. Analogous to Echo's HandlerFunc.

type Hub added in v0.4.0 

type Hub = pubsub.Hub[[]Message]

Hub coordinates broadcasting of messages between Turbo Streams message publishers and subscribers.

type Message 

type Message struct {
	Action   Action
	Target   string
	Targets  string
	Template string
	Data     interface{}
}

Message represents a Turbo Stream message which can be rendered to a string using the specified template.

type MiddlewareFunc 

type MiddlewareFunc = pubsub.MiddlewareFunc[*Context]

MiddlewareFunc defines a function to process middleware. Analogous to Echo's MiddlewareFunc.

type Route 

type Route = pubsub.Route

Route contains a handler and information for matching against requests. Analogous to Echo's Route.

type Router 

type Router interface {
	pubsub.Router[*Context]
	MSG(streamName string, h HandlerFunc, m ...MiddlewareFunc) *Route
}

Router is the subset of Broker methods for adding handlers to routes.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.