Pelican Object Subscribe
How a client learns of new and changed objects under a federation path: it asks the director for a notify-capable origin, opens an authenticated WebSocket to that origin's notification server, and subscribes to a topic derived from the path.
This page is interactive documentation, in the spirit of a Swagger "Try it out": fill in the form and each step below shows the exchange pelican object subscribe performs, with your values.
The written requests and responses are the ones the Pelican client exchanges.
A browser cannot send or read some of those parts (an Authorization header on a WebSocket, the headers of a redirect), so the page makes equivalent requests.
Open What this page actually sent under a step for the difference.
Try it out
How do I get an access token?
If the namespace requires authorization, subscribing needs a token with a storage.read scope covering the path.
On the origin host, with the origin's own config and signing keys, mint one:
pelican-server origin token create \ --profile wlcg \ --lifetime 3600 \ --subject my-user \ --scope "storage.read:/" \ --audience "https://origin.example.org:8443"
The --audience must be one the origin accepts: its own URL (Origin.Url, the default Origin.TokenAudience) or the WLCG wildcard.
A literal any is rejected with 'aud' claim verification failed in the origin log.
Scopes are relative to the federation prefix, and the export must not set PublicReads if you want to require the token.
The token's iss must be one of the export's trusted issuers.
When the token expires, the origin closes the subscription.
Running this against a development federation
The page calls the director and origin from your browser, so it must trust their certificates. For a self-signed development federation, open the director's and the origin's HTTPS URLs in a tab once and accept the certificate. The director allows cross-origin requests; the origin's WebSocket accepts any page origin.
1. Ask the director for a notify-capable origin
The notify query asks for origins that advertise the Notify capability.
The client sends no token, and does not follow the redirect: the headers are the answer.
Location points at the origin that serves the path, and X-Pelican-Namespace carries the namespace, whether it requires a token, and the notify-url, the origin's WebSocket endpoint.
The client subscribes at the notify-url, not at the redirect.
2. Open the notification connection
A WebSocket begins as an HTTP request that asks to switch protocols.
The origin authenticates that request: a bearer token in the Authorization header, checked against the origin's trusted issuers.
A request with no token is anonymous and can subscribe only to publicly readable paths.
3. Topic and subscription
The federation path and depth become a STOMP destination, <client id>/<depth>/<protocol>/<object path>.
Depth counts levels below the path: objects directly in it are one level down.
The protocol is the URL's scheme.
The client id names the subscription: the SUBSCRIBE's subscription header repeats it, and reconnecting with the same one resumes events that were not acknowledged.
4. Notifications
The origin lists the watched part of the namespace on an interval and announces objects that are new or modified. Each message body is a JSON string holding the object's federation path. The client acknowledges each one once handled, so an unacknowledged notification is sent again.
Waiting for a subscription.