management

Documentation

Index

• Constants
• func AsClosed(err error) *websocket.CloseError
• func IntoClientEvent[T EventStartStreaming | EventStopStreaming](e *ClientEvent, eventType ClientEventType) (*T, bool)
• func IntoServerEvent[T EventLog](e *ServerEvent, eventType ServerEventType) (*T, bool)
• func IsClosed(err error, log *zerolog.Logger) bool
• func ValidateAccessTokenQueryMiddleware(next http.Handler) http.Handler
• func WriteEvent(c *websocket.Conn, ctx context.Context, event any) error
• type ClientEvent
  • func ReadClientEvent(c *websocket.Conn, ctx context.Context) (*ClientEvent, error)
• type ClientEventType
• type EventLog
• type EventStartStreaming
• type EventStopStreaming
• type Log
• type LogEventType
  • func ParseLogEventType(s string) (LogEventType, bool)
  • func (l LogEventType) MarshalJSON() ([]byte, error)
  • func (l LogEventType) String() string
  • func (e *LogEventType) UnmarshalJSON(data []byte) error
• type LogLevel
  • func ParseLogLevel(l string) (LogLevel, bool)
  • func (l LogLevel) MarshalJSON() ([]byte, error)
  • func (l LogLevel) String() string
  • func (l *LogLevel) UnmarshalJSON(data []byte) error
• type Logger
  • func NewLogger() *Logger
  • func (l *Logger) ActiveSession(actor actor) *session
  • func (l *Logger) ActiveSessions() int
  • func (l *Logger) Listen(session *session)
  • func (l *Logger) Remove(session *session)
  • func (l *Logger) Write(p []byte) (int, error)
  • func (l *Logger) WriteLevel(level zerolog.Level, p []byte) (n int, err error)
• type LoggerListener
• type ManagementService
  • func New(managementHostname string, enableDiagServices bool, serviceIP string, ...) *ManagementService
  • func (m *ManagementService) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type ServerEvent
  • func ReadServerEvent(c *websocket.Conn, ctx context.Context) (*ServerEvent, error)
• type ServerEventType
• type StreamingFilters

Constants

const (
	UnknownClientEventType ClientEventType = ""
	StartStreaming         ClientEventType = "start_streaming"
	StopStreaming          ClientEventType = "stop_streaming"

	UnknownServerEventType ServerEventType = ""
	Logs                   ServerEventType = "logs"
)

const (
	// TimeKey aligns with the zerolog.TimeFieldName
	TimeKey = "time"
	// LevelKey aligns with the zerolog.LevelFieldName
	LevelKey = "level"
	// LevelKey aligns with the zerolog.MessageFieldName
	MessageKey = "message"
	// EventTypeKey is the custom JSON key of the LogEventType in ZeroLogEvent
	EventTypeKey = "event"
	// FieldsKey is a custom JSON key to match and store every other key for a zerolog event
	FieldsKey = "fields"
)

const (
	// In the current state, an invalid command was provided by the client
	StatusInvalidCommand websocket.StatusCode = 4001

	// There are a limited number of available streaming log sessions that cloudflared will service, exceeding this
	// value will return this error to incoming requests.
	StatusSessionLimitExceeded websocket.StatusCode = 4002

	// There is a limited idle time while not actively serving a session for a request before dropping the connection.
	StatusIdleLimitExceeded websocket.StatusCode = 4003
)

Functions

func AsClosed

func AsClosed(err error) *websocket.CloseError

func IntoClientEvent

func IntoClientEvent[T EventStartStreaming | EventStopStreaming](e *ClientEvent, eventType ClientEventType) (*T, bool)

IntoClientEvent unmarshals the provided ClientEvent into the proper type.

func IntoServerEvent

func IntoServerEvent[T EventLog](e *ServerEvent, eventType ServerEventType) (*T, bool)

IntoServerEvent unmarshals the provided ServerEvent into the proper type.

func IsClosed

func IsClosed(err error, log *zerolog.Logger) bool

IsClosed returns true if the websocket error is a websocket.CloseError; returns false if not a websocket.CloseError

func ValidateAccessTokenQueryMiddleware

func ValidateAccessTokenQueryMiddleware(next http.Handler) http.Handler

HTTP middleware setting the parsed access_token claims in the request context

func WriteEvent

func WriteEvent(c *websocket.Conn, ctx context.Context, event any) error

WriteEvent will write a Event type message to the websocket connection.

Types

type ClientEvent

type ClientEvent struct {
	Type ClientEventType `json:"type,omitempty"`
	// contains filtered or unexported fields
}

ClientEvent is the base struct that informs, based of the Type field, which Event type was provided from the client.

func ReadClientEvent

func ReadClientEvent(c *websocket.Conn, ctx context.Context) (*ClientEvent, error)

ReadEvent will read a message from the websocket connection and parse it into a valid ClientEvent.

type ClientEventType

type ClientEventType string

ClientEventType represents the event types that can come from the client

type EventLog

type EventLog struct {
	ServerEvent
	Logs []*Log `json:"logs"`
}

EventLog is the event that the server sends to the client with the log events.

type EventStartStreaming

type EventStartStreaming struct {
	ClientEvent
	Filters *StreamingFilters `json:"filters,omitempty"`
}

EventStartStreaming signifies that the client wishes to start receiving log events. Additional filters can be provided to augment the log events requested.

type EventStopStreaming

type EventStopStreaming struct {
	ClientEvent
}

EventStopStreaming signifies that the client wishes to halt receiving log events.

type Log

type Log struct {
	Time    string                 `json:"time,omitempty"`
	Level   LogLevel               `json:"level,omitempty"`
	Message string                 `json:"message,omitempty"`
	Event   LogEventType           `json:"event,omitempty"`
	Fields  map[string]interface{} `json:"fields,omitempty"`
}

Log is the basic structure of the events that are sent to the client.

type LogEventType

type LogEventType int8

LogEventType is the way that logging messages are able to be filtered. Example: assigning LogEventType.Cloudflared to a zerolog event will allow the client to filter for only the Cloudflared-related events.

const (
	// Cloudflared events are signficant to cloudflared operations like connection state changes.
	// Cloudflared is also the default event type for any events that haven't been separated into a proper event type.
	Cloudflared LogEventType = iota
	HTTP
	TCP
	UDP
)

func ParseLogEventType

func ParseLogEventType(s string) (LogEventType, bool)

func (LogEventType) MarshalJSON

func (l LogEventType) MarshalJSON() ([]byte, error)

func (LogEventType) String

func (l LogEventType) String() string

func (*LogEventType) UnmarshalJSON

func (e *LogEventType) UnmarshalJSON(data []byte) error

type LogLevel

type LogLevel int8

LogLevel corresponds to the zerolog logging levels "panic", "fatal", and "trace" are exempt from this list as they are rarely used and, at least the the first two are limited to failure conditions that lead to cloudflared shutting down.

const (
	Debug LogLevel = 0
	Info  LogLevel = 1
	Warn  LogLevel = 2
	Error LogLevel = 3
)

func ParseLogLevel

func ParseLogLevel(l string) (LogLevel, bool)

func (LogLevel) MarshalJSON

func (l LogLevel) MarshalJSON() ([]byte, error)

func (LogLevel) String

func (l LogLevel) String() string

func (*LogLevel) UnmarshalJSON

func (l *LogLevel) UnmarshalJSON(data []byte) error

type Logger

type Logger struct {

	// Unique logger that isn't a io.Writer of the list of zerolog writers. This helps prevent management log
	// statements from creating infinite recursion to export messages to a session and allows basic debugging and
	// error statements to be issued in the management code itself.
	Log *zerolog.Logger
	// contains filtered or unexported fields
}

Logger manages the number of management streaming log sessions

func NewLogger

func NewLogger() *Logger

func (*Logger) ActiveSession

func (l *Logger) ActiveSession(actor actor) *session

func (*Logger) ActiveSessions

func (l *Logger) ActiveSessions() int

func (*Logger) Listen

func (l *Logger) Listen(session *session)

func (*Logger) Remove

func (l *Logger) Remove(session *session)

func (*Logger) Write

func (l *Logger) Write(p []byte) (int, error)

Write will write the log event to all sessions that have available capacity. For those that are full, the message will be dropped. This function is the interface that zerolog expects to call when a log event is to be written out.

func (*Logger) WriteLevel

func (l *Logger) WriteLevel(level zerolog.Level, p []byte) (n int, err error)

type LoggerListener

type LoggerListener interface {
	// ActiveSession returns the first active session for the requested actor.
	ActiveSession(actor) *session
	// ActiveSession returns the count of active sessions.
	ActiveSessions() int
	// Listen appends the session to the list of sessions that receive log events.
	Listen(*session)
	// Remove a session from the available sessions that were receiving log events.
	Remove(*session)
}

type ManagementService

type ManagementService struct {
	// The management tunnel hostname
	Hostname string
	// contains filtered or unexported fields
}

func New

func New(managementHostname string,
	enableDiagServices bool,
	serviceIP string,
	clientID uuid.UUID,
	label string,
	log *zerolog.Logger,
	logger LoggerListener,
) *ManagementService

func (*ManagementService) ServeHTTP

func (m *ManagementService) ServeHTTP(w http.ResponseWriter, r *http.Request)

type ServerEvent

type ServerEvent struct {
	Type ServerEventType `json:"type,omitempty"`
	// contains filtered or unexported fields
}

ServerEvent is the base struct that informs, based of the Type field, which Event type was provided from the server.

func ReadServerEvent

func ReadServerEvent(c *websocket.Conn, ctx context.Context) (*ServerEvent, error)

ReadEvent will read a message from the websocket connection and parse it into a valid ServerEvent.

type ServerEventType

type ServerEventType string

ServerEventType represents the event types that can come from the server

type StreamingFilters

type StreamingFilters struct {
	Events   []LogEventType `json:"events,omitempty"`
	Level    *LogLevel      `json:"level,omitempty"`
	Sampling float64        `json:"sampling,omitempty"`
}