streaming

Documentation

Index

• Constants
• type Module
  • func New(processor processing.Processor, dTicker time.Duration, wsBuf int) *Module
  • func (m *Module) Route(...)
  • func (m *Module) StreamGETHandler(c *gin.Context)

Constants

const (
	// BasePath is the path for the streaming api, minus the 'api' prefix
	BasePath = "/v1/streaming"

	// StreamQueryKey is the query key for the type of stream being requested
	StreamQueryKey = "stream"

	// AccessTokenQueryKey is the query key for an oauth access token that should be passed in streaming requests.
	AccessTokenQueryKey = "access_token"
	// AccessTokenHeader is the header for an oauth access token that can be passed in streaming requests instead of AccessTokenQueryKey
	//nolint:gosec
	AccessTokenHeader = "Sec-Websocket-Protocol"
)

Types

type Module

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

func New

func New(processor processing.Processor, dTicker time.Duration, wsBuf int) *Module

func (*Module) Route

func (m *Module) Route(attachHandler func(method string, path string, f ...gin.HandlerFunc) gin.IRoutes)

func (*Module) StreamGETHandler

func (m *Module) StreamGETHandler(c *gin.Context)

StreamGETHandler swagger:operation GET /api/v1/streaming streamGet

Initiate a websocket connection for live streaming of statuses and notifications.

The scheme used should *always* be `wss`. The streaming basepath can be viewed at `/api/v1/instance`.

On a successful connection, a code `101` will be returned, which indicates that the connection is being upgraded to a secure websocket connection.

As long as the connection is open, various message types will be streamed into it.

GoToSocial will ping the connection every 30 seconds to check whether the client is still receiving.

If the ping fails, or something else goes wrong during transmission, then the connection will be dropped, and the client will be expected to start it again.

---
tags:
- streaming

produces:
- application/json

schemes:
- wss

parameters:
-
	name: access_token
	type: string
	description: Access token for the requesting account.
	in: query
	required: true
-
	name: stream
	type: string
	description: |-
		Type of stream to request.

		Options are:

		`user`: receive updates for the account's home timeline.
		`public`: receive updates for the public timeline.
		`public:local`: receive updates for the local timeline.
		`hashtag`: receive updates for a given hashtag.
		`hashtag:local`: receive local updates for a given hashtag.
		`list`: receive updates for a certain list of accounts.
		`direct`: receive updates for direct messages.
	in: query
	required: true

security:
- OAuth2 Bearer:
	- read:streaming

responses:
	'101':
		schema:
			type: object
			properties:
				stream:
					type: array
					items:
						type: string
						enum:
						- user
						- public
						- public:local
						- hashtag
						- hashtag:local
						- list
						- direct
				event:
					description: |-
						The type of event being received.

						`update`: a new status has been received.
						`notification`: a new notification has been received.
						`delete`: a status has been deleted.
						`filters_changed`: not implemented.
					type: string
					enum:
					- update
					- notification
					- delete
					- filters_changed
				payload:
					description: |-
						The payload of the streamed message.
						Different depending on the `event` type.

						If present, it should be parsed as a string.

						If `event` = `update`, then the payload will be a JSON string of a status.
						If `event` = `notification`, then the payload will be a JSON string of a notification.
						If `event` = `delete`, then the payload will be a status ID.
					type: string
					example: "{\"id\":\"01FC3TZ5CFG6H65GCKCJRKA669\",\"created_at\":\"2021-08-02T16:25:52Z\",\"sensitive\":false,\"spoiler_text\":\"\",\"visibility\":\"public\",\"language\":\"en\",\"uri\":\"https://gts.superseriousbusiness.org/users/dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669\",\"url\":\"https://gts.superseriousbusiness.org/@dumpsterqueer/statuses/01FC3TZ5CFG6H65GCKCJRKA669\",\"replies_count\":0,\"reblogs_count\":0,\"favourites_count\":0,\"favourited\":false,\"reblogged\":false,\"muted\":false,\"bookmarked\":fals…//gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/original/019036W043D8FXPJKSKCX7G965.png\",\"header_static\":\"https://gts.superseriousbusiness.org/fileserver/01JNN207W98SGG3CBJ76R5MVDN/header/small/019036W043D8FXPJKSKCX7G965.png\",\"followers_count\":33,\"following_count\":28,\"statuses_count\":126,\"last_status_at\":\"2021-08-02T16:25:52Z\",\"emojis\":[],\"fields\":[]},\"media_attachments\":[],\"mentions\":[],\"tags\":[],\"emojis\":[],\"card\":null,\"poll\":null,\"text\":\"a\"}"
	'401':
		description: unauthorized
	'400':
		description: bad request