pubsub: PubSub management

PubSub commands are low level command to handle a PubSub Service. They are using the generic pubsub arguments

For most of those commands, pubsub commands are used to specify the destination item.

set

Publish a pubsub item.

stdin is used to get the raw XML of the payload of the item to publish.

-f KEY VALUE, --field KEY VALUE can be used to specify publish options, i.e. option which must be set if the node already exists, or used if the node is to be created, see XEP-0060 §7.1.5 for details.

In the same way as for create, -F, --full-prefix can be used if you need to specify the full option name.

example

Create an item with a custom note XML:

$ echo '<note xmlns="http://example.net/mynotes">this is a note</note>' | li pubsub set -n "notes"

get

Retrieve items from specified node. Default output is prettified and highlighted XML.

example

Retrieve the last 5 notes from our custom notes node:

$ li pubsub get -n notes -m 5

delete

Delete an item from a node. If -N, --notify is specified, subscribers will be notified of the item retraction.

By default a confirmation is requested before deletion is requested to the PubSub service, but you can override this behaviour by using -f, --force option.

example

Delete item with id 123456 from a node:

$ li pubsub delete -n test_node -i 123456

edit

Edit the raw XML of an item payload using your local editor (the one set in $EDITOR).

If you don’t change anything or publish an empty blog post, the edition will be cancelled.

draft commands can be used.

example

Edit the last note in our custom node:

$ li pubsub edit -n notes -L

rename

Move a item to a new ID. As there is currently no “rename” or “move” operation in XMPP PubSub, this is done by republishing the item with the new ID, then deleting the old item if the publication succeed.

This is notably useful when user friendly URL based on ID are used, and one need to fix a typo or something else.

example

Rename a PubSub item with ID 123 to 456:

$ li pubsub rename -n some_node -i 123 456

subscribe

Subscribe to a node.

Subscription is used to get notifications from the node in case of new/updated item or deletion.

example

Subscribe to an information blog:

$ li pubsub subscribe -n informations -s pubsub.example.net

unsubscribe

Unsubscribe from a node.

example

Unsubscribe from an information blog:

$ li pubsub unsubscribe -n informations -s pubsub.example.net

subscriptions

Retrieve subscriptions for all nodes on a service.

-n NODE, --node NODE can be used to request subscriptions for a specific node (e.g. if it has subscription with multiple subIDs).

example

Retrieve all subscriptions on a pubsub service:

$ li pubsub subscriptions -s pubsub@example.net

affiliations

Retrieve affiliations for all nodes at a service.

-n NODE, --node NODE can be used to request affiliation for a specific node.

examples

Retrieve all affiliations at a pubsub service:

$ li pubsub affiliations -s pubsub@example.net

Retrieve affiliation for the notes node:

$ li pubsub affiliations -s pubsub@example.net -n notes

transform

Modify items using an external command.

transform will retrieve requested items, and will send each of them to the standard input (stdin) of the specified command. The output of the command will be used, it can be 3 things:

  • a raw XML of the modified item, in which case the item will be republished

  • the string SKIP, in which case the item will be ignored

  • the string DELETE, in which case the item will be retracted

By default a dry run is done, which means that no item is modified or deleted. To actually do the transformation, you have to use --apply argument.

If you have to modify the publisher of an item, you need specific privileges. The --admin allows you do to that, but it must be supported by your PubSub service (currently only Libervia PubSub supports this non standard feature).

To modify all items of a node, use the -A, --all option. This will use RSM repetitively until all items are treated. Of course that means that your PubSub service must support RSM. The items being republished, they will reappear on top of your node, that’s why it is recommended to use --order-by creation option when supported by the service, to keep consistent order and avoid transforming the same items several times.

If the command you’re using exit with a non zero code, the process will stop. Use -I, --ignore_errors if you want to continue transformation even if an non zero code is returned.

example

Imagine that you want to replace all occurrences of “sàt” by “Libervia” in your personal blog. You first create a Python script like this:

#!/usr/bin/env python3

import sys
item_raw = sys.stdin.read()
if not "sàt" in item_raw:
    print("SKIP")
else:
    print(item_raw.replace("sàt", "Libervia"))

And save it a some location, e.g. ~/expand_sat.py (don’t forget to make it executable with chmod +x ~/expand_sat.py).

To be sure it’s safe, you can first do a dry-run and check the result:

$ li pubsub transform -n urn:xmpp:microblog:0 -A -o creation ~/expand_sat.py

Once you have checked that you have the expected behaviour, you can apply the transformations:

$ li pubsub transform -n urn:xmpp:microblog:0 -A -o creation --apply ~/expand_sat.py

And that’s it. You can use the same technique for more complex transformations, including modifying the XML (with Python, you can easily do that with standard xml.etree.ElementTree module or with lxml.etree).

uri

Build an XMPP URI linking to a PubSub node or item.

example

Build a link to personal blog:

$ li pubsub uri -n urn:xmpp:microblog:0

node

Subcommands for node management. Please check pubsub/node: PubSub nodes management.

hook

Subcommands for hooks management. Please check pubsub/hook: PubSub hooks management.