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
}
Index ¶
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func RandAlphanumBytes ¶
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 ¶
This error is sent to Sub.OnError when a subscription is denied.
func (*DeniedError) Error ¶
func (e *DeniedError) Error() string
type RequestError ¶
This error is sent to Sub.OnError when unexpected requests are sent.
func (*RequestError) Error ¶
func (e *RequestError) Error() string
type ResponseError ¶
func (*ResponseError) Error ¶
func (e *ResponseError) Error() 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 (*Sub) CancelRenewal ¶
Cancels the automatic renewal of the subscription. If there was no renewal to cancel, returns false.
func (*Sub) ServeHTTP ¶
func (s *Sub) ServeHTTP(rw http.ResponseWriter, r *http.Request)
Implements http.Handler to handle incoming subscription requests.
func (*Sub) Subscribe ¶
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 ¶
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 ¶
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.