sub

package module
v0.0.0-...-4141db7 Latest Latest
Warning

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

Go to latest
Published: Jan 30, 2018 License: MIT Imports: 15 Imported by: 0

README

sub

Build Status

Sub is a go library to consume PubSubHubbub (PuSH) hubs. PuSH is a server-to-server update protocol. It's used to notify servers about changes on other servers. Check out the documentation for examples of using this library.

If you don't need fine-grained control of your subscriptions, check out push-sub. It's a daemon which maintains subscriptions and calls specified commands when messages arrive.

Documentation

Overview

This packages provides a subscriber for v0.4 of the PubSubHubbub protocol. It provides features like discovery and automated renewal while aiming to remain flexible and secure.

Example
package main

import (
	"fmt"
	"net"
	"net/http"
	"net/url"
	"os"

	"github.com/0xcaff/sub"
)

func main() {
	listenAddr := ":80"

	// create and initialize subscription
	s := sub.New()
	s.Topic = MustParseUrl("https://example.com/feed.xml")

	// discover the hub
	s.Discover()

	// register handler, we are using a randomly generate endpoint because
	// anyone can make a GET request to change our internal state if they know
	// the subscription callback url.
	randomEndpoint := "/subs/" + string(sub.RandAlphanumBytes(99))
	s.Callback = MustParseUrl("https://this-server.com" + randomEndpoint)

	// add callbacks
	s.OnError = func(err error) {
		// these errors are non-critical, just log them
		fmt.Println("Error", err)
	}

	s.OnMessage = func(req *http.Request, body []byte) {
		fmt.Println("Message", body)
	}

	s.OnRenewLease = func(s *sub.Sub) {
		err := s.Subscribe()
		if err != nil {
			fmt.Println("Subscription Error", err)
		}

		os.Exit(1)
	}

	mux := &http.ServeMux{}
	mux.Handle(randomEndpoint, s)

	// start listening before we start subscribing so that validation by the hub
	// doesn't fail
	listener, err := net.Listen("tcp", listenAddr)
	if err != nil {
		panic(err)
	}

	// subscribe
	err = s.Subscribe()
	if err != nil {
		panic(err)
	}

	// start serving
	server := &http.Server{Addr: listenAddr, Handler: mux}
	err = server.Serve(listener)
	if err != nil {
		panic(err)
	}
}

func MustParseUrl(raw string) *url.URL {
	url, err := url.Parse(raw)
	if err != nil {
		panic(err)
	}

	return url
}
Output:

Index

Examples

Constants

This section is empty.

Variables

This section is empty.

Functions

func RandAlphanumBytes

func RandAlphanumBytes(n int) []byte

A helper function create and fill a slice of length n with characters from a-zA-Z0-9_-. It panics if there are any problems getting random bytes.

Types

type DeniedError

type DeniedError struct {
	Topic  string
	Reason string
}

This error is sent to Sub.OnError when a subscription is denied.

func (*DeniedError) Error

func (e *DeniedError) Error() string

type RequestError

type RequestError struct {
	Request *http.Request
	Message string
}

This error is sent to Sub.OnError when unexpected requests are sent.

func (*RequestError) Error

func (e *RequestError) Error() string

type ResponseError

type ResponseError struct {
	Response *http.Response
	Message  string
}

func (*ResponseError) Error

func (e *ResponseError) Error() string

type State

type State int
const (
	Unsubscribed State = iota
	Requested
	Subscribed
)

func (State) String

func (i State) String() string

type Sub

type Sub struct {
	// The url of the topic which this subscription receives events for.
	Topic *url.URL

	// The url of the hub. This can be discovered using Sub.Discover()
	Hub *url.URL

	// The url which is provided to the hub during subscription and renewal.
	// This url is allowed to contain query parameters.
	Callback *url.URL

	// When a non-PubSubHubbub message from the hub arrives, this callback is
	// called. The body on request is always closed.
	OnMessage func(request *http.Request, body []byte)

	// When a broken message is handled or the hub cancels our subscription,
	// this callback is called.
	OnError func(err error)

	// Called when it is time to renew the lease. This can be used to make
	// changes during lease renewals. Errors returned from here are sent to
	// OnError.
	OnRenewLease func(subscription *Sub)

	// The client which is used to make requests to the hub.
	Client *http.Client

	// The < 200 byte long secret used to validate that messages are coming from
	// the real server.
	Secret []byte

	// The current state of the client.
	State State

	// The time at which the lease will expire.
	LeaseExpiry time.Time
	// contains filtered or unexported fields
}

Represents a subscription to a topic on a PubSubHubbub hub.

func New

func New() *Sub

func (*Sub) CancelRenewal

func (s *Sub) CancelRenewal() bool

Cancels the automatic renewal of the subscription. If there was no renewal to cancel, returns false.

func (*Sub) Discover

func (s *Sub) Discover() error

Discovers a hub from s.Topic using s.Client.

func (*Sub) ServeHTTP

func (s *Sub) ServeHTTP(rw http.ResponseWriter, r *http.Request)

Implements http.Handler to handle incoming subscription requests.

func (*Sub) Subscribe

func (s *Sub) Subscribe() error

Sends a subscription request to the hub. If there is no error, the request completed sucessfully. State is only changed after the callback server verifies.

func (*Sub) SubscribeWithLease

func (s *Sub) SubscribeWithLease(leaseSeconds int) error

Sends a subscription request to the hub suggesting a lease time of leaseSeconds. The hub gets the final decision on the lease time.

func (*Sub) Unsubscribe

func (s *Sub) Unsubscribe() error

Sends an un-subscription request to the hub. If no error is returned, the request completed sucessfully. State is only changed after the callback server verifies.

Directories

Path Synopsis

Jump to

Keyboard shortcuts

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