client

Documentation

Overview

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

Index

• Constants
• type Client
  • func New(config *Config) *Client
  • func (c *Client) Poll(topic string, options ...SubscribeOption) ([]*Message, error)
  • func (c *Client) Publish(topic, message string, options ...PublishOption) (*Message, error)
  • func (c *Client) Subscribe(topic string, options ...SubscribeOption) string
  • func (c *Client) Unsubscribe(subscriptionID string)
  • func (c *Client) UnsubscribeAll(topic string)
• type Config
  • func LoadConfig(filename string) (*Config, error)
  • func NewConfig() *Config
• type Message
• type PublishOption
  • func WithDelay(delay string) PublishOption
  • func WithNoCache() PublishOption
  • func WithNoFirebase() PublishOption
  • func WithPriority(priority string) PublishOption
  • func WithTags(tags []string) PublishOption
  • func WithTagsList(tags string) PublishOption
  • func WithTitle(title string) PublishOption
• type RequestOption
  • func WithHeader(header, value string) RequestOption
  • func WithQueryParam(param, value string) RequestOption
• type SubscribeOption
  • func WithFilter(param, value string) SubscribeOption
  • func WithMessageFilter(message string) SubscribeOption
  • func WithPoll() SubscribeOption
  • func WithPriorityFilter(priority int) SubscribeOption
  • func WithScheduled() SubscribeOption
  • func WithSince(since string) SubscribeOption
  • func WithSinceAll() SubscribeOption
  • func WithSinceDuration(since time.Duration) SubscribeOption
  • func WithSinceUnixTime(since int64) SubscribeOption
  • func WithTagsFilter(tags []string) SubscribeOption
  • func WithTitleFilter(title string) SubscribeOption

Constants

const (
	MessageEvent   = "message"
	KeepaliveEvent = "keepalive"
	OpenEvent      = "open"
)

Event type constants

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

Types

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.

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"`
	Subscribe   []struct {
		Topic   string            `yaml:"topic"`
		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

	// 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 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 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