Docblocks, a handful of tests, but not enough
This commit is contained in:
parent
fa9d6444f5
commit
e3dfea1991
9 changed files with 121 additions and 12 deletions
|
@ -1,3 +1,4 @@
|
|||
// Package client provides a ntfy client to publish and subscribe to topics
|
||||
package client
|
||||
|
||||
import (
|
||||
|
@ -12,12 +13,14 @@ import (
|
|||
"time"
|
||||
)
|
||||
|
||||
// Event type constants
|
||||
const (
|
||||
MessageEvent = "message"
|
||||
KeepaliveEvent = "keepalive"
|
||||
OpenEvent = "open"
|
||||
)
|
||||
|
||||
// Client is the ntfy client that can be used to publish and subscribe to ntfy topics
|
||||
type Client struct {
|
||||
Messages chan *Message
|
||||
config *Config
|
||||
|
@ -25,6 +28,7 @@ type Client struct {
|
|||
mu sync.Mutex
|
||||
}
|
||||
|
||||
// Message is a struct that represents a ntfy message
|
||||
type Message struct {
|
||||
ID string
|
||||
Event string
|
||||
|
@ -42,6 +46,7 @@ type subscription struct {
|
|||
cancel context.CancelFunc
|
||||
}
|
||||
|
||||
// New creates a new Client using a given Config
|
||||
func New(config *Config) *Client {
|
||||
return &Client{
|
||||
Messages: make(chan *Message),
|
||||
|
@ -50,6 +55,14 @@ func New(config *Config) *Client {
|
|||
}
|
||||
}
|
||||
|
||||
// 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 (c *Client) Publish(topic, message string, options ...PublishOption) error {
|
||||
topicURL := c.expandTopicURL(topic)
|
||||
req, _ := http.NewRequest("POST", topicURL, strings.NewReader(message))
|
||||
|
@ -68,6 +81,15 @@ func (c *Client) Publish(topic, message string, options ...PublishOption) error
|
|||
return err
|
||||
}
|
||||
|
||||
// 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 (c *Client) Poll(topic string, options ...SubscribeOption) ([]*Message, error) {
|
||||
ctx := context.Background()
|
||||
messages := make([]*Message, 0)
|
||||
|
@ -85,6 +107,22 @@ func (c *Client) Poll(topic string, options ...SubscribeOption) ([]*Message, err
|
|||
return messages, <-errChan
|
||||
}
|
||||
|
||||
// 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.
|
||||
//
|
||||
// Example:
|
||||
// c := client.New(client.NewConfig())
|
||||
// c.Subscribe("mytopic")
|
||||
// for m := range c.Messages {
|
||||
// fmt.Printf("New message: %s", m.Message)
|
||||
// }
|
||||
func (c *Client) Subscribe(topic string, options ...SubscribeOption) string {
|
||||
c.mu.Lock()
|
||||
defer c.mu.Unlock()
|
||||
|
@ -98,6 +136,11 @@ func (c *Client) Subscribe(topic string, options ...SubscribeOption) string {
|
|||
return topicURL
|
||||
}
|
||||
|
||||
// Unsubscribe unsubscribes from a topic that has been previously subscribed with Subscribe.
|
||||
//
|
||||
// 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).
|
||||
func (c *Client) Unsubscribe(topic string) {
|
||||
c.mu.Lock()
|
||||
defer c.mu.Unlock()
|
||||
|
@ -107,7 +150,6 @@ func (c *Client) Unsubscribe(topic string) {
|
|||
return
|
||||
}
|
||||
sub.cancel()
|
||||
return
|
||||
}
|
||||
|
||||
func (c *Client) expandTopicURL(topic string) string {
|
||||
|
@ -128,7 +170,7 @@ func handleSubscribeConnLoop(ctx context.Context, msgChan chan *Message, topicUR
|
|||
case <-ctx.Done():
|
||||
log.Printf("Connection to %s exited", topicURL)
|
||||
return
|
||||
case <-time.After(5 * time.Second):
|
||||
case <-time.After(10 * time.Second): // TODO Add incremental backoff
|
||||
}
|
||||
}
|
||||
}
|
||||
|
|
|
@ -1,9 +1,11 @@
|
|||
package client
|
||||
|
||||
const (
|
||||
// DefaultBaseURL is the base URL used to expand short topic names
|
||||
DefaultBaseURL = "https://ntfy.sh"
|
||||
)
|
||||
|
||||
// Config is the config struct for a Client
|
||||
type Config struct {
|
||||
DefaultHost string
|
||||
Subscribe []struct {
|
||||
|
@ -12,6 +14,7 @@ type Config struct {
|
|||
}
|
||||
}
|
||||
|
||||
// NewConfig creates a new Config struct for a Client
|
||||
func NewConfig() *Config {
|
||||
return &Config{
|
||||
DefaultHost: DefaultBaseURL,
|
||||
|
|
|
@ -1,49 +1,94 @@
|
|||
package client
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"net/http"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
type RequestOption func(r *http.Request) error
|
||||
// RequestOption is a generic request option that can be added to Client calls
|
||||
type RequestOption = func(r *http.Request) error
|
||||
|
||||
// PublishOption is an option that can be passed to the Client.Publish call
|
||||
type PublishOption = RequestOption
|
||||
|
||||
// SubscribeOption is an option that can be passed to a Client.Subscribe or Client.Poll call
|
||||
type SubscribeOption = RequestOption
|
||||
|
||||
// WithTitle adds a title to a message
|
||||
func WithTitle(title string) PublishOption {
|
||||
return WithHeader("X-Title", title)
|
||||
}
|
||||
|
||||
// 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 WithPriority(priority string) PublishOption {
|
||||
return WithHeader("X-Priority", priority)
|
||||
}
|
||||
|
||||
func WithTags(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 WithTagsList(tags string) PublishOption {
|
||||
return WithHeader("X-Tags", tags)
|
||||
}
|
||||
|
||||
// WithTags adds a list of a tags to a message
|
||||
func WithTags(tags []string) PublishOption {
|
||||
return WithTagsList(strings.Join(tags, ","))
|
||||
}
|
||||
|
||||
// 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 WithDelay(delay string) PublishOption {
|
||||
return WithHeader("X-Delay", delay)
|
||||
}
|
||||
|
||||
// WithNoCache instructs the server not to cache the message server-side
|
||||
func WithNoCache() PublishOption {
|
||||
return WithHeader("X-Cache", "no")
|
||||
}
|
||||
|
||||
// WithNoFirebase instructs the server not to forward the message to Firebase
|
||||
func WithNoFirebase() PublishOption {
|
||||
return WithHeader("X-Firebase", "no")
|
||||
}
|
||||
|
||||
// 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 WithSince(since string) SubscribeOption {
|
||||
return WithQueryParam("since", since)
|
||||
}
|
||||
|
||||
// WithSinceAll instructs the server to return all messages for the given topic from the server
|
||||
func WithSinceAll() SubscribeOption {
|
||||
return WithSince("all")
|
||||
}
|
||||
|
||||
// WithSinceDuration instructs the server to return all messages since the given duration ago
|
||||
func WithSinceDuration(since time.Duration) SubscribeOption {
|
||||
return WithSinceUnixTime(time.Now().Add(-1 * since).Unix())
|
||||
}
|
||||
|
||||
// WithSinceUnixTime instructs the server to return only messages newer or equal to the given timestamp
|
||||
func WithSinceUnixTime(since int64) SubscribeOption {
|
||||
return WithSince(fmt.Sprintf("%d", since))
|
||||
}
|
||||
|
||||
// WithPoll instructs the server to close the connection after messages have been returned. Don't use this option
|
||||
// directly. Use Client.Poll instead.
|
||||
func WithPoll() SubscribeOption {
|
||||
return WithQueryParam("poll", "1")
|
||||
}
|
||||
|
||||
// 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 WithScheduled() SubscribeOption {
|
||||
return WithQueryParam("scheduled", "1")
|
||||
}
|
||||
|
||||
// WithHeader is a generic option to add headers to a request
|
||||
func WithHeader(header, value string) RequestOption {
|
||||
return func(r *http.Request) error {
|
||||
if value != "" {
|
||||
|
@ -53,6 +98,7 @@ func WithHeader(header, value string) RequestOption {
|
|||
}
|
||||
}
|
||||
|
||||
// WithQueryParam is a generic option to add query parameters to a request
|
||||
func WithQueryParam(param, value string) RequestOption {
|
||||
return func(r *http.Request) error {
|
||||
if value != "" {
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue