Skip to content

Next into main: v97 #936

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kprosise merged 3 commits into from
May 14, 2026
Merged

Next into main: v97 #936

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
f2d7b8f
rm: Remove "pull queues" from manual
doanac Apr 23, 2026
65a2a2c
Fix issues around fioctl_version
kprosise Apr 30, 2026
8044fdd
update version switcher for v97 release
kprosise May 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions .github/workflows/publish-dev.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,7 @@ jobs:

- name: Add latest Fioctl docs
run: |
export fv=$(wget -q -O- https://api.github.com/repos/foundriesio/fioctl/releases/latest | grep tag_name | sed -E 's/.*"([^"]+)".*/\1/')
wget -O /tmp/fioctl https://github.com/foundriesio/fioctl/releases/download/${fv}/fioctl-linux-amd64
wget -O /tmp/fioctl https://github.com/foundriesio/fioctl/releases/latest/download/fioctl-linux-amd64
chmod +x /tmp/fioctl
/tmp/fioctl gen-rst source/appendix/fioctl-command-reference/

Expand Down
3 changes: 1 addition & 2 deletions .github/workflows/publish-main.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,7 @@ jobs:

- name: Add latest Fioctl docs
run: |
export fv=$(wget -q -O- https://api.github.com/repos/foundriesio/fioctl/releases/latest | grep tag_name | sed -E 's/.*"([^"]+)".*/\1/')
wget -O /tmp/fioctl https://github.com/foundriesio/fioctl/releases/download/${fv}/fioctl-linux-amd64
wget -O /tmp/fioctl https://github.com/foundriesio/fioctl/releases/latest/download/fioctl-linux-amd64
chmod +x /tmp/fioctl
/tmp/fioctl gen-rst source/appendix/fioctl-command-reference/

Expand Down
4 changes: 1 addition & 3 deletions source/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,6 @@

mp_version = os.environ.get('MP_UPDATE_VERSION')
lmp_build = os.environ.get('LMP_BUILD')
fioctl_version = os.environ.get('fv')
if mp_version is None:
try:
git_version = subprocess.check_output(['git', 'describe', '--tags'])
Expand Down Expand Up @@ -213,8 +212,7 @@
rst_epilog = '''
.. |docker_tag| replace:: {}
.. |manifest_tag| replace:: {}
.. |fioctl_version| replace:: {}
'''.format(docker_tag, manifest_tag, fioctl_version)
'''.format(docker_tag, manifest_tag)

# -- PDF Configuration --------------------------------------------------------

Expand Down
18 changes: 5 additions & 13 deletions source/getting-started/install-fioctl/index.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,17 +47,13 @@
.. attention:: Make sure you have ``curl`` installed.

1. Download a Linux binary to a directory on your ``PATH``.
For example, to download version |fioctl_version| on Linux, define the version:

.. parsed-literal::

FIOCTL_VERSION="|fioctl_version|"
For example, to download the latest version on Linux:

Download the binary with curl:

.. code-block:: console

$ sudo curl -o /usr/local/bin/fioctl -LO https://github.com/foundriesio/fioctl/releases/download/$FIOCTL_VERSION/fioctl-linux-amd64
$ sudo curl -o /usr/local/bin/fioctl -LO https://github.com/foundriesio/fioctl/releases/latest/download/fioctl-linux-amd64

Check warning on line 56 in source/getting-started/install-fioctl/index.rst

View workflow job for this annotation

GitHub Actions / runner / vale 

[vale] reported by reviewdog 🐶
[Fio-docs.Branding-and-names] Use 'Fioctl' instead of 'fioctl'

Raw Output:
{"message": "[Fio-docs.Branding-and-names] Use 'Fioctl' instead of 'fioctl'", "location": {"path": "source/getting-started/install-fioctl/index.rst", "range": {"start": {"line": 56, "column": 119}}}, "severity": "INFO"}

2. Make the :ref:`ref-fioctl` binary executable:

Expand All @@ -73,21 +69,17 @@

1. Download a Darwin binary from the `GitHub Releases`_ page to a directory on your ``PATH``.

For example, to download version |fioctl_version| on macOS, define the version:

.. parsed-literal::

FIOCTL_VERSION="|fioctl_version|"
For example, to download the latest version on macOS:

Download the binary with curl:

.. code-block:: console

$ sudo curl -o /usr/local/bin/fioctl -L https://github.com/foundriesio/fioctl/releases/download/$FIOCTL_VERSION/fioctl-darwin-amd64
$ sudo curl -o /usr/local/bin/fioctl -L https://github.com/foundriesio/fioctl/releases/latest/download/fioctl-darwin-amd64

.. important::

For MacOS running on a Apple M1 processor, replace ``fioctl-darwin-amd64`` with ``fioctl-darwin-arm64``, and set ``FIOCTL_VERSION`` to v0.21 or newer.
For MacOS running on a Apple M1 processor, replace ``fioctl-darwin-amd64`` with ``fioctl-darwin-arm64``.

2. Make the :ref:`ref-fioctl` binary executable:

Expand Down
47 changes: 9 additions & 38 deletions source/reference-manual/factory/event-queues.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,47 +16,21 @@ These include:
* When an OTA update starts and completes.

Event queues are implemented using Google PubSub_ to provide a well understood and tested framework.
There are two types of event queues:

* Push: Works as a webhook_ service.
Events are sent to a managed URL where they can be processed.

* Pull: Works like a typical message queue system where one can write their own client to receive and process events.

The PubSub documentation includes a very useful guide_ for deciding which approach will work best for you.
They also include a wide range of `client libraries`_ for consuming the Pull API.
FoundriesFactory leverages "push subscriptions" as the delivery mechanism for events.
PubSub subscriptions are created with default retention, expiration, and acknowledgement values_.

Implementation Details
----------------------

Each FoundriesFactory is given a single PubSub Topic.
Each Push and Pull queue created by a customer results in the creation of a PubSub subscription.
Each Topic results in the creation of a PubSub "push" subscription.
The FoundriesFactory API provides a thin, multi-tenant friendly wrapper to manage everything.

.. note::
For performance reasons, new push queues can take up to five minutes before they start receiving events.

Creating a Pull Queue
---------------------

A pull queue can be created using Fioctl:

.. code-block:: console

$ fioctl event-queues mk-pull <name> <where to save creds-file>
$ fioctl event-queues mk-pull docs-example $HOME/.fio-pull-queue.creds

Fioctl can also monitor this queue:
For performance reasons, new queues can take up to five minutes before they start receiving events.

.. code-block:: console

$ fioctl event-queues listen docs-example $HOME/.fio-pull-queue.creds

This command also serves as a reference example_ on implementing a pull queue listener.

Creating a Push Queue
---------------------
Creating a Queue
----------------

A push queue requires a little up front work:

Expand Down Expand Up @@ -91,8 +65,8 @@ Once the server is running, you can create a push queue with:

At this point events will start showing up in the example server.

Push Queue Payloads
~~~~~~~~~~~~~~~~~~~
Event Queue Payloads
~~~~~~~~~~~~~~~~~~~~

Incoming HTTP requests will look similar to:

Expand All @@ -112,8 +86,8 @@ Incoming HTTP requests will look similar to:
"subscription":"projects/osf-prod/subscriptions/xxxxxxxx"
}

Push Queue Security
~~~~~~~~~~~~~~~~~~~
Event Queue Security
~~~~~~~~~~~~~~~~~~~~

Incoming requests will include a header, ``Authorization: Bearer <jwt>``.
This JWT is signed with one of Google's own private keys.
Expand Down Expand Up @@ -237,9 +211,6 @@ DEVICE_PUBKEY_CHANGE
.. _PubSub:
https://cloud.google.com/pubsub/docs/overview

.. _webhook:
https://en.wikipedia.org/wiki/Webhook

.. _guide:
https://cloud.google.com/pubsub/docs/subscriber

Expand Down
Loading