文件列表:

.editorconfig (174, 2022-04-14)
LICENSE (1051, 2022-04-14)
examples/ (0, 2022-04-14)
examples/hub/ (0, 2022-04-14)
examples/hub/main.go (1337, 2022-04-14)
examples/multi-port/ (0, 2022-04-14)
examples/multi-port/main.go (2343, 2022-04-14)
examples/publisher/ (0, 2022-04-14)
examples/publisher/main.go (4001, 2022-04-14)
examples/single-port/ (0, 2022-04-14)
examples/single-port/main.go (2079, 2022-04-14)
examples/sniffer/ (0, 2022-04-14)
examples/sniffer/main.go (2487, 2022-04-14)
examples/subscriber/ (0, 2022-04-14)
examples/subscriber/main.go (1140, 2022-04-14)
examples/topic-announcement/ (0, 2022-04-14)
examples/topic-announcement/main.go (2713, 2022-04-14)
go.mod (921, 2022-04-14)
go.sum (6098, 2022-04-14)
hub.go (20314, 2022-04-14)
publisher.go (5059, 2022-04-14)
shared.go (1187, 2022-04-14)
staticcheck.conf (28, 2022-04-14)
subscriber.go (11325, 2022-04-14)
subscriber_test.go (1242, 2022-04-14)

# go-websub go-websub is a websub subscriber, publisher, and hub library written in go. It passes all of the [websub.rocks](https://websub.rocks/) tests for publishers and hubs, and *almost* all of them for subscribers. Inspired by https://github.com/tystuyfzand/websub-client and https://github.com/tystuyfzand/websub-server. ## Examples See the [./examples/](./examples/) directory for examples of using a [subscriber](./examples/subscriber/main.go), [publisher](./examples/publisher/main.go), and [hub](./examples/hub/main.go). ## Importing ``` go get github.com/notnotquinn/go-websub ``` ## Quick links - [Features](#features) - [Subscriber features](#subscriber-features) - [methods](#subscriber-methods) - [Publisher features](#publisher-features) - [methods](#publisher-methods) - [Hub features](#hub-features) - [methods](#hub-methods) - [Spec conformance classes](#spec-conformance-classes) - [Subscriber conformance](#subscriber-conformance) - [Publisher conformance](#hub-conformance) - [Hub conformance](#hub-conformance) ## Features - [ ] BIG: Does not (currently) persist state between restarts. - [x] Can run subscriber, publisher, and hub from one server, on one port, if needed. (see [examples/single-port](./examples/single-port/main.go)) ### Subscriber features - [ ] BIG: Does not (currently) persist state between restarts. - [ ] Not completely spec compliant. (see [Subscriber conformance](#subscriber-conformance)) - [x] Functions independently from publisher and hub. - [x] Subscribe & unsubscribe to topics. - [x] Simple function callback system, with access to subscription meta-data. - [x] Request specific lease duration. - [x] Provide `hub.secret` and verify hub signature. - [ ] Automatically refresh expiring subscriptions. #### Subscriber methods Interact with the subscriber via a Go API: - [x] Subscribe to topic URLs with callback. - Example: ```go subscription, err := s.Subscribe( // Topic URL that exposes Link headers for "hub" and "self". "https://example.com/topic1", // for authenticated content distribution (maximum of 200 characters) "random bytes", // Callback function is called when the subscriber receives a valid // request from the hub, not on invalid ones // (for example ones with a missing or invalid hub signature) func(sub *websub.SubscriberSubscription, contentType string, body io.Reader) { fmt.Println("Received content!") // do something... }, ) if err != nil { // handle } ``` - [x] Unsubscribe from topics. - Example: ```go err = s.Unsubscribe(subscription) if err != nil { // handle } ``` ### Publisher features - [ ] BIG: Does not (currently) persist state between restarts. - [x] Completely spec compliant. - [x] Functions independently from subscriber and hub. - [x] Advertise topic and hub URLs for previously published topics. - [x] Send publish requests for topic URLs that arent under the publishers base URL. - [x] Send both `hub.topic` and `hub.url` on publish requests. - [x] Treat `https://example.com/baseURL/topic/` equal to `https://example.com/baseURL/topic` for incoming requests. - [x] Optionally advertise topic and hub URLs for unpublished topics. - [x] Optionally post content in publish request. (see [publisher publishing methods](#publisher-publishing-methods) #2) #### Publisher methods Interact with the publisher via a Go API: - [x] Publish content with content-type. - Example: ```go err = p.Publish( // Topic URL p.BaseURL()+"/topic1", // Content Type "text/plain", // Content []byte("Hello, WebSub!"), ) if err != nil { // handle } ``` ### Hub features - [ ] BIG: Does not (currently) persist state between restarts. - [x] Completely spec compliant. - [x] Functions independently from subscriber and publiser. - [x] Configurable retry limits for distribution requests. - [x] Configurable lease length limits and default lease length. - [x] Configurable User-Agent for HTTP requests on behaf of the hub. - [x] Configure one of "sha1", "sha256", "sha384", and "sha512" for signing publish requests. - [x] Optionally expose all known topic URLs as a JSON array to `/topics` and provide websub updates for new topics. - [x] Optionally accept publish requests with the body as the content. (see [Hub accepted publishing methods](#hub-accepted-publishing-methods) #2) #### Hub methods Interact with the hub via a Go API: - [x] Custom subscription validation. - Example: ```go // Deny any subscription where the callback URL is not under "example.com" h.AddValidator(func(sub *websub.HubSubscription) (ok bool, reason string) { parsed, err := url.Parse(sub.Callback) if err != nil { return false, "invalid callback url" } if parsed.Host != "example.com" { return false, "callback host not allowed" } return true, "" }) ``` - [x] Sniff on published topics. (to all or one topic, as if you were subscribed) - Example: ```go // List the topic url as an empty string to listen to all publishes. h.AddSniffer("https://example.com/topic1", func(topic, contentType string, content []byte) { fmt.Printf("New publish on \"https://example.com/topic1\" !") }, ) ``` - [x] Publish content via method call. - Example: ```go // no return value h.Publish("https://example.com/topic1", "Content-Type", []byte("Content")) ``` - [x] Get all topic URLs programmatically. - Example: ```go fmt.Printf("%#v", h.GetTopics()) // []string{"https://example.com/topic1", https://example.com/topic2", ...} ``` ## Spec conformance classes As per the [websub spec](https://www.w3.org/TR/websub/#conformance-classes). ### Subscriber conformance The included subscriber technically does not follow the websub spec, because it does not support discovering links from HTML tags, Atom feeds, or RSS feeds. The subscriber still discovers topics form their `Link` headers, so this does not impact the subscriber's interaction with the hub or publisher implemented here, but it may end up being a problem if you are planning on subscribing to other publisher implementations that don't provide `Link` headers for their topics. A conforming subscriber: - [2/5] MUST support each discovery mechanism in the specified order to discover the topic and hub URLs as described in [Discovery ](https://www.w3.org/TR/websub/#discovery) - [x] HTTP header discovery - [ ] HTML tag discovery - [ ] Atom feed discovery - [ ] RSS feed discovery - [x] Discovery priority - [x] MUST send a subscription request as described in [Subscriber Sends Subscription Request ](https://www.w3.org/TR/websub/#subscriber-sends-subscription-request). - [x] MUST acknowledge a content distribution request with an HTTP 2xx status code. - [x] MAY request a specific lease duration - [x] MAY request that a subscription is deactivated using the "unsubscribe" mechanism. - [x] MAY include a secret in the subscription request, and if it does, then MUST use the secret to verify the signature in the [content distribution request](https://www.w3.org/TR/websub/#authenticated-content-distribution). ### Publisher conformance A conforming publisher: - [x] MUST advertise topic and hub URLs for a given resource URL as described in [Discovery](https://www.w3.org/TR/websub/#discovery). #### Publisher publishing methods There are 2 options to publish, which are both supported by the hub: 1. (default) Send a POST request (as Content-Type: `application/x-www-form-urlencoded`) with the keys `hub.mode` set to `publish`, and `hub.url` & `hub.topic` both set to the updated URL in the body as a form. 2. (opt-in) Send a POST request with the same keys as above in the query string parameters, and the key `hub.content` equal to `body`. The hub will not make any request to the topic URL, and instead will distribute the body of the POST request, and associated Content-Type to subscribers. This method is disabled by default for the hub. The updated URL is duplicated because of possible hub implementation variations. ### Hub conformance A conforming hub: - [x] MUST accept a subscription request with the parameters hub.callback, hub.mode and hub.topic. - [x] MUST accept a subscription request with a hub.secret parameter. - [x] MAY respect the requested lease duration in subscription requests. - Respects requested lease duration if it is within a configurable allowed range, otherwise it is pinned to the maximum or minimum limit. - [x] MUST allow subscribers to re-request already active subscriptions. - [x] MUST support unsubscription requests. - [x] MUST send content distribution requests with a matching content type of the topic URL. (See [Content Negotiation ](https://www.w3.org/TR/websub/#content-negotiation)) - [x] MUST send a X-Hub-Signature header if the subscription was made with a hub.secret as described in [Authenticated Content Distribution ](https://www.w3.org/TR/websub/#authenticated-content-distribution). - [ ] MAY reduce the payload of the content distribution to a diff of the contents for supported formats as described in [Content Distribution ](https://www.w3.org/TR/websub/#content-distribution). #### Hub accepted publishing methods There are two ways for publishers to publish to the hub, which match the ones availible for the provided publisher: 1. Send a POST request (as Content-Type: `application/x-www-form-urlencoded`) with the keys `hub.mode` equal to `publish`, one or both of `hub.topic` and `hub.url` equal to the topic URL that was updated in the body as a form. If both are provided `hub.topic` is used. The hub makes a GET request to the topic URL and distributes the content to subscribers, with the correct Content-Type. 2. (disabled by default) Send a POST request with the same keys as above in the query string parameters, and the key `hub.content` equal to `body`. The hub will not make any request to the topic URL, and instead will distribute the body of the POST request, and associated Content-Type to subscribers.

近期下载者：

相关文件：

评论：[我要评论] [举报此文件]

收藏者：