cloudrelay

package
v2.25.4 Latest Latest
Warning

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

Go to latest
Published: Nov 4, 2026 License: GPL-3.0 Imports: 19 Imported by: 0

Documentation

Overview

Package cloudrelay connects a Dagu server to the Dagu Cloud relay, which holds the server's public webhook URLs and hands over what senders post to them, and carries calls from Dagu Cloud to the server.

Index

Constants

View Source
const AssertionHeader = "Dagu-Assertion"

AssertionHeader carries, to Handler.Call, the assertion Dagu Cloud signed for the call, which the relay passes on unread.

View Source
const ErrorTooManyHooks = "too_many_hooks"

ErrorTooManyHooks is the relay's refusal of a set larger than the ticket allows.

View Source
const HandshakeSlack = "slack"

HandshakeSlack has the relay answer Slack's URL check, which needs its challenge back at once, even while the server is away.

Variables

View Source
var (
	// ErrSilent means the relay stopped answering.
	ErrSilent = errors.New("the relay stopped answering")
	// ErrReplaced means another connection from this server took over.
	ErrReplaced = errors.New("another connection from this server took over the relay")
	// ErrDropped means Dagu Cloud disconnected this server.
	ErrDropped = errors.New("the server was disconnected from Dagu Cloud")
)
View Source
var (
	OutcomeStarted = Outcome{/* contains filtered or unexported fields */}
	OutcomeIgnored = Outcome{/* contains filtered or unexported fields */}
	OutcomeFailed  = Outcome{/* contains filtered or unexported fields */}
)

Functions

This section is empty.

Types

type Conn

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

Conn is a connection this server holds open to the relay.

func Dial

func Dial(ctx context.Context, client *http.Client, ticket Ticket, hello Hello) (*Conn, error)

Dial opens a connection to the relay a ticket names and introduces this server.

func (*Conn) Close

func (c *Conn) Close() error

Close ends the connection without serving it.

func (*Conn) Serve

func (c *Conn) Serve(ctx context.Context, h Handler) error

Serve answers what the relay sends until the connection ends or ctx is done. Deliveries run concurrently. It returns nil when the relay ended the connection on schedule.

func (*Conn) SetHooks

func (c *Conn) SetHooks(ctx context.Context, hooks []Hook) error

SetHooks gives the relay the whole set of this server's hooks, replacing the set it holds. Webhooks waiting for a hook left out are dropped. The relay answers through Handler.Hooked.

type Delivery

type Delivery struct {
	// ID tells this delivery apart from every other, across repeats.
	ID       string
	Hook     string
	Received time.Time
	Header   http.Header
	Body     []byte
}

Delivery is a webhook the relay kept for one of this server's hooks.

type Handler

type Handler struct {
	// Delivery takes a webhook and reports what became of it. The relay
	// sends a webhook again on the next connection until it hears an
	// outcome, so the same delivery can arrive more than once.
	Delivery func(ctx context.Context, d Delivery) Outcome
	// Hooked receives the relay's answer to each set of hooks.
	Hooked func(h Hooked)
	// Missed receives, for each hook, how many webhooks the relay dropped
	// since it last told this server. Each count is told once.
	Missed func(missed []Missed)
	// Call serves the calls Dagu Cloud sends through the relay, each with its
	// assertion in AssertionHeader. A call the relay cancels has its
	// request's context canceled.
	Call http.Handler
}

Handler serves what the relay sends to this server.

type Hello

type Hello struct {
	Name    string
	Version string
	// Instance names the process opening a connection for calls, which the
	// relay keeps beside the connections of the server's other processes. It
	// is empty for the scheduler's connection.
	Instance string
}

Hello is what the server tells the relay first.

type Hook

type Hook struct {
	ID    string
	Token string
	// Handshake names that sender: HandshakeSlack, or empty for none.
	Handshake string
}

Hook is one public webhook URL as the relay knows it: an ID the server chooses, the token its URL ends in, and the sender whose URL check the relay answers for it.

type Hooked

type Hooked struct {
	URL string
	// Error is "too_many_hooks" when the set is larger than the ticket allows.
	Error string
}

Hooked is the relay's answer to a set of hooks: the URL they share, or why it refused the set.

type Missed

type Missed struct {
	Hook    string `json:"hook"`
	Expired int    `json:"expired"`
	Refused int    `json:"refused"`
}

Missed counts the webhooks the relay dropped for one hook: those that waited past its 7 days, and those it refused while too many waited.

type Outcome

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

Outcome is what became of a delivery. The relay forgets a delivery on any outcome but a retry.

func OutcomeRetry

func OutcomeRetry(after time.Duration) Outcome

OutcomeRetry asks the relay to keep a delivery and send it again after the given time, holding back its hook's later deliveries until then.

func (Outcome) String

func (o Outcome) String() string

String is the outcome's name on the wire.

type Ticket

type Ticket struct {
	Token string `json:"token"`
	// URL is the relay's WebSocket endpoint.
	URL string `json:"url"`
	// MaxHooks is the most public webhook URLs the server's plan allows.
	MaxHooks int `json:"max_hooks"`
}

Ticket is what a server opens its relay connection with. It is good for a few minutes, so every connection asks for a new one.

func RequestAccessTicket

func RequestAccessTicket(ctx context.Context, client *http.Client, creds license.CloudCredentials) (Ticket, error)

RequestAccessTicket asks Dagu Cloud for the ticket of a connection that takes calls from Dagu Cloud. Dagu Cloud refuses it while the server's workspace has neither a plan nor a trial.

func RequestTicket

func RequestTicket(ctx context.Context, client *http.Client, creds license.CloudCredentials) (Ticket, error)

RequestTicket asks Dagu Cloud for a relay ticket with the server's license credentials: the scheduler's, which takes webhooks.

type TicketRefusedError

type TicketRefusedError struct {
	StatusCode int
	Message    string
}

TicketRefusedError means Dagu Cloud refused a ticket to these credentials: the server is not connected, or not allowed public webhook URLs. Asking again soon does not help.

func (*TicketRefusedError) Error

func (e *TicketRefusedError) Error() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL