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            = "/v1/streaming"          // path for the streaming api, minus the 'api' prefix
	StreamQueryKey      = "stream"                 // type of stream being requested
	StreamListKey       = "list"                   // id of list being requested
	StreamTagKey        = "tag"                    // name of tag being requested
	AccessTokenQueryKey = "access_token"           // oauth access token
	AccessTokenHeader   = "Sec-Websocket-Protocol" //nolint:gosec
)

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
-
	name: list
	type: string
	description: |-
		ID of the list to subscribe to.
		Only used if stream type is 'list'.
	in: query
-
	name: tag
	type: string
	description: |-
		Name of the tag to subscribe to.
		Only used if stream type is 'hashtag' or 'hashtag:local'.
	in: query

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