client

package
v1.31.0 Latest Latest
Warning

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

 Go to latest Published: Feb 15, 2023 License: Apache-2.0 Imports: 14 Imported by: 2

Documentation

Overview

Package client provides a ntfy client to publish and subscribe to topics

Index

Constants

View Source 
const (
	MessageEvent     = "message"
	KeepaliveEvent   = "keepalive"
	OpenEvent        = "open"
	PollRequestEvent = "poll_request"
)

Event type constants

View Source 
const (
	// DefaultBaseURL is the base URL used to expand short topic names
	DefaultBaseURL = "https://ntfy.sh"
)

Variables

This section is empty.

Functions

This section is empty.

Types

type Attachment added in v1.13.0 

type Attachment struct {
	Name    string `json:"name"`
	Type    string `json:"type,omitempty"`
	Size    int64  `json:"size,omitempty"`
	Expires int64  `json:"expires,omitempty"`
	URL     string `json:"url"`
	Owner   string `json:"-"` // IP address of uploader, used for rate limiting
}

Attachment represents a message attachment

type Client 

type Client struct {
	Messages chan *Message
	// contains filtered or unexported fields
}

Client is the ntfy client that can be used to publish and subscribe to ntfy topics

func New 

func New(config *Config) *Client

New creates a new Client using a given Config

func (*Client) Poll 

func (c *Client) Poll(topic string, options ...SubscribeOption) ([]*Message, error)

Poll queries a topic for all (or a limited set) of messages. Unlike Subscribe, this method only polls for messages and does not subscribe to messages that arrive after this call.

A topic can be either a full URL (e.g. https://myhost.lan/mytopic), a short URL which is then prepended https:// (e.g. myhost.lan -> https://myhost.lan), or a short name which is expanded using the default host in the config (e.g. mytopic -> https://ntfy.sh/mytopic).

By default, all messages will be returned, but you can change this behavior using a SubscribeOption. See WithSince, WithSinceAll, WithSinceUnixTime, WithScheduled, and the generic WithQueryParam.

func (*Client) Publish 

func (c *Client) Publish(topic, message string, options ...PublishOption) (*Message, error)

Publish sends a message to a specific topic, optionally using options. See PublishReader for details.

func (*Client) PublishReader added in v1.12.0 

func (c *Client) PublishReader(topic string, body io.Reader, options ...PublishOption) (*Message, error)

PublishReader sends a message to a specific topic, optionally using options.

A topic can be either a full URL (e.g. https://myhost.lan/mytopic), a short URL which is then prepended https:// (e.g. myhost.lan -> https://myhost.lan), or a short name which is expanded using the default host in the config (e.g. mytopic -> https://ntfy.sh/mytopic).

To pass title, priority and tags, check out WithTitle, WithPriority, WithTagsList, WithDelay, WithNoCache, WithNoFirebase, and the generic WithHeader.

func (*Client) Subscribe 

func (c *Client) Subscribe(topic string, options ...SubscribeOption) string

Subscribe subscribes to a topic to listen for newly incoming messages. The method starts a connection in the background and returns new messages via the Messages channel.

A topic can be either a full URL (e.g. https://myhost.lan/mytopic), a short URL which is then prepended https:// (e.g. myhost.lan -> https://myhost.lan), or a short name which is expanded using the default host in the config (e.g. mytopic -> https://ntfy.sh/mytopic).

By default, only new messages will be returned, but you can change this behavior using a SubscribeOption. See WithSince, WithSinceAll, WithSinceUnixTime, WithScheduled, and the generic WithQueryParam.

The method returns a unique subscriptionID that can be used in Unsubscribe.

Example: 

c := client.New(client.NewConfig())
subscriptionID := c.Subscribe("mytopic")
for m := range c.Messages {
  fmt.Printf("New message: %s", m.Message)
}

func (*Client) Unsubscribe 

func (c *Client) Unsubscribe(subscriptionID string)

Unsubscribe unsubscribes from a topic that has been previously subscribed to using the unique subscriptionID returned in Subscribe.

func (*Client) UnsubscribeAll 

func (c *Client) UnsubscribeAll(topic string)

UnsubscribeAll unsubscribes from a topic that has been previously subscribed with Subscribe. If there are multiple subscriptions matching the topic, all of them are unsubscribed from.

A topic can be either a full URL (e.g. https://myhost.lan/mytopic), a short URL which is then prepended https:// (e.g. myhost.lan -> https://myhost.lan), or a short name which is expanded using the default host in the config (e.g. mytopic -> https://ntfy.sh/mytopic).

type Config 

type Config struct {
	DefaultHost     string  `yaml:"default-host"`
	DefaultUser     string  `yaml:"default-user"`
	DefaultPassword *string `yaml:"default-password"`
	DefaultCommand  string  `yaml:"default-command"`
	Subscribe       []struct {
		Topic    string            `yaml:"topic"`
		User     string            `yaml:"user"`
		Password *string           `yaml:"password"`
		Command  string            `yaml:"command"`
		If       map[string]string `yaml:"if"`
	} `yaml:"subscribe"`
}

Config is the config struct for a Client

func LoadConfig 

func LoadConfig(filename string) (*Config, error)

LoadConfig loads the Client config from a yaml file

func NewConfig 

func NewConfig() *Config

NewConfig creates a new Config struct for a Client

type Message 

type Message struct {
	ID         string
	Event      string
	Time       int64
	Topic      string
	Message    string
	Title      string
	Priority   int
	Tags       []string
	Click      string
	Icon       string
	Attachment *Attachment

	// Additional fields
	TopicURL       string
	SubscriptionID string
	Raw            string
}

Message is a struct that represents a ntfy message

type PublishOption 

type PublishOption = RequestOption

PublishOption is an option that can be passed to the Client.Publish call

func WithActions added in v1.21.0 

func WithActions(value string) PublishOption

WithActions adds custom user actions to the notification. The value can be either a JSON array or the simple format definition. See https://ntfy.sh/docs/publish/#action-buttons for details.

func WithAttach added in v1.12.0 

func WithAttach(attach string) PublishOption

WithAttach sets a URL that will be used by the client to download an attachment

func WithBasicAuth added in v1.14.0 

func WithBasicAuth(user, pass string) PublishOption

WithBasicAuth adds the Authorization header for basic auth to the request

func WithClick added in v1.12.0 

func WithClick(url string) PublishOption

WithClick makes the notification action open the given URL as opposed to entering the detail view

func WithDelay 

func WithDelay(delay string) PublishOption

WithDelay instructs the server to send the message at a later date. The delay parameter can be a Unix timestamp, a duration string or a natural langage string. See https://ntfy.sh/docs/publish/#scheduled-delivery for details.

func WithEmail added in v1.9.0 

func WithEmail(email string) PublishOption

WithEmail instructs the server to also send the message to the given e-mail address

func WithFilename added in v1.12.0 

func WithFilename(filename string) PublishOption

WithFilename sets a filename for the attachment, and/or forces the HTTP body to interpreted as an attachment

func WithIcon added in v1.28.0 

func WithIcon(icon string) PublishOption

WithIcon makes the notification use the given URL as its icon

func WithMessage added in v1.12.0 

func WithMessage(message string) PublishOption

WithMessage sets the notification message. This is an alternative way to passing the message body.

func WithNoCache 

func WithNoCache() PublishOption

WithNoCache instructs the server not to cache the message server-side

func WithNoFirebase 

func WithNoFirebase() PublishOption

WithNoFirebase instructs the server not to forward the message to Firebase

func WithPriority 

func WithPriority(priority string) PublishOption

WithPriority adds a priority to a message. The priority can be either a number (1=min, 5=max), or the corresponding names (see util.ParsePriority).

func WithTags 

func WithTags(tags []string) PublishOption

WithTags adds a list of a tags to a message

func WithTagsList 

func WithTagsList(tags string) PublishOption

WithTagsList adds a list of tags to a message. The tags parameter must be a comma-separated list of tags. To use a slice, use WithTags instead

func WithTitle 

func WithTitle(title string) PublishOption

WithTitle adds a title to a message

type RequestOption 

type RequestOption = func(r *http.Request) error

RequestOption is a generic request option that can be added to Client calls

func WithHeader 

func WithHeader(header, value string) RequestOption

WithHeader is a generic option to add headers to a request

func WithQueryParam 

func WithQueryParam(param, value string) RequestOption

WithQueryParam is a generic option to add query parameters to a request

type SubscribeOption 

type SubscribeOption = RequestOption

SubscribeOption is an option that can be passed to a Client.Subscribe or Client.Poll call

func WithFilter 

func WithFilter(param, value string) SubscribeOption

WithFilter is a generic subscribe option meant to be used to filter for certain messages only

func WithMessageFilter 

func WithMessageFilter(message string) SubscribeOption

WithMessageFilter instructs the server to only return messages that match the exact message

func WithPoll 

func WithPoll() SubscribeOption

WithPoll instructs the server to close the connection after messages have been returned. Don't use this option directly. Use Client.Poll instead.

func WithPriorityFilter 

func WithPriorityFilter(priority int) SubscribeOption

WithPriorityFilter instructs the server to only return messages with the matching priority. Not that messages without priority also implicitly match priority 3.

func WithScheduled 

func WithScheduled() SubscribeOption

WithScheduled instructs the server to also return messages that have not been sent yet, i.e. delayed/scheduled messages (see WithDelay). The messages will have a future date.

func WithSince 

func WithSince(since string) SubscribeOption

WithSince limits the number of messages returned from the server. The parameter since can be a Unix timestamp (see WithSinceUnixTime), a duration (WithSinceDuration) the word "all" (see WithSinceAll).

func WithSinceAll 

func WithSinceAll() SubscribeOption

WithSinceAll instructs the server to return all messages for the given topic from the server

func WithSinceDuration 

func WithSinceDuration(since time.Duration) SubscribeOption

WithSinceDuration instructs the server to return all messages since the given duration ago

func WithSinceUnixTime 

func WithSinceUnixTime(since int64) SubscribeOption

WithSinceUnixTime instructs the server to return only messages newer or equal to the given timestamp

func WithTagsFilter 

func WithTagsFilter(tags []string) SubscribeOption

WithTagsFilter instructs the server to only return messages that contain all of the given tags

func WithTitleFilter 

func WithTitleFilter(title string) SubscribeOption

WithTitleFilter instructs the server to only return messages with a title that match the exact string

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.