Skip to content
This repository has been archived by the owner on Mar 31, 2024. It is now read-only.

Latest commit

 

History

History
109 lines (84 loc) · 3.62 KB

README.md

File metadata and controls

109 lines (84 loc) · 3.62 KB
Raw

WebSubKit/WebSubSubscriber

A WebSub Subscriber implementation written in Swift for usage with 💧 Vapor.

🗳️ Implemented Features

Discovery

  • 100: HTTP header discovery - discovers the hub and self URLs from HTTP headers
  • 101: HTML tag discovery - discovers the hub and self URLs from the HTML <link> tags
  • 102: Atom feed discovery - discovers the hub and self URLs from the XML <link> tags
  • 103: RSS feed discovery - discovers the hub and self URLs from the XML <atom:link> tags
  • 104: Discovery priority - prioritizes the hub and self in HTTP headers over the links in the body

Subscription

  • 1xx: Successfully creates a subscription
  • 200: Subscribing to a URL that reports a different rel=self
  • 201: Subscribing to a topic URL that sends an HTTP 302 temporary redirect
  • 202: Subscribing to a topic URL that sends an HTTP 301 permanent redirect
  • 203: Subscribing to a hub that sends a 302 temporary redirect
  • 204: Subscribing to a hub that sends a 301 permanent redirect
  • 205: Rejects a verification request with an invalid topic URL
  • 1xx: Requests a subscription using a secret (optional)
    • Please select the signature method(s) that the subscriber recognizes. All methods listed below are currently acceptable for the hub to choose:
    • sha1
    • sha256
    • sha384
    • sha512
  • 1xx: Requests a subscription with a specific lease_seconds (optional, hub may ignore)
  • Callback URL is unique per subscription (should)
  • Callback URL is an unguessable URL (should)
  • 1xx: Sends an unsubscription request

Distribution

  • 300: Returns HTTP 2xx when the notification payload is delivered
  • 1xx: Verifies a valid signature for authenticated distribution
  • 301: Rejects a distribution request with an invalid signature
  • 302: Rejects a distribution request with no signature when the subscription was made with a secret

📥 Installation

Swift Package Manager

To integrate WebSubSubscriber into your project, specify it in your Package.swift file:

let package = Package(
    ...
    dependencies: [
        .package(url: "https://github.com/WebSubKit/websub-subscriber.git", from: "0.12.0"),
    ]
    ...
    targets: [
        .executableTarget(
            dependencies: [
                ...
                .product(name: "WebSubSubscriber", package: "websub-subscriber"),
                ...
            ],
        ),
    ]
    ...
)

⛏️ Usage

Migrate the subscriptions table

    app.migrations.add(CreateSubscriptionsTable())
    ...
    try await app.autoMigrate()

Create a new controller that conforms to SubscriberRouteCollection

struct SubscriberController: SubscriberRouteCollection {
    
    let path: PathComponent = ""
    
        func receiving(from request: Request, received: (validPayload: Request, subscription: SubscriptionModel)) async throws -> Response {
        // handle the delivered payload here ...
        return Response(status: .noContent)
    }
    
}

Register the controller to app

    try app.register(collection: SubscriberController())

Created routes

GET  (path)/subscribe 
    -> discover topic and hub, called by user to create a new subscription to a topic via the advertised hub by the publisher 
GET  (path)/callback/(unique-subscription-id)
    -> verify the subscription, called by the hub to verify the requested subscription
POST (path)/callback/(unique-subscription-id)
    -> receive payload from the hub, called by the hub to deliver payload published by the publisher