Skip to content

overview.org

Latest commit

 

History

History
587 lines (510 loc) · 20.7 KB

overview.org

File metadata and controls

587 lines (510 loc) · 20.7 KB

Bazaar Overview

This document is intended for distributors of Bazaar to learn how to configure the application.

Features

Here is a short list of some of the things Bazaar can do, beyond the basics of managing software through the GUI:

  • Queue an arbitrary number of transactions (a catch-all term for installations, updates, and removals) during which you may close all windows or continue to append new transactions freely
  • Display a “Curated” page which you may extensively customize with YAML, as will be discussed later. This is a way to highlight applications which you believe might be of interest.
    • Curated configuration files are constantly monitored for filesystem events, meaning you can update them and see the changes immediate reflected in the GUI
    • You can have any number of curated configuration files; they will concatenate in the GUI in the order they were provided
  • Access data from flathub, such as the latest or most popular applications
  • Filter through applications very quickly using a very forgiving search routine
    • For instance, if a user quickly types ikscep into the search field, Inkscape will still appear as the top result.
  • Run in the background and respond to desktop search queries with application info, using the same search routine as in-application
    • GNOME will work out of the box, as Bazaar implements the org.gnome.Shell.SearchProvider2 dbus interface
    • KDE Plasma will require a krunner plugin
  • Hide applications you do not want users to see with blocklists, which is useful for discouraging the use of certain packages which you deem to be broken.
  • Manage an arbitrary amount of windows and keep them synchronized
  • Communicate with, and invoke operations on, the main daemon through the command line

CLI Usage

You can start the bazaar daemon like this:

bazaar [ARGS] [PACKAGE PATH/URI]

To avoid spawning a window, use:

bazaar --no-window [ARGS] [PACKAGE PATH/URI]

[PACKAGE PATH/URI] could be a .flatpakref file. flatpak+https and regular https is supported.

Comptime Vars

Bazaar provides a few compile time meson options:

  • hardcoded_main_config_path: Embeds a path to a main configuration file into Bazaar. If this is not defined at compile time, Bazaar will never attempt to read a main config. See the “Hooks” section of this document to see an example config file.

THESE NEXT TWO OPTIONS ARE DEPRECATED. GOING FORWARD, PLEASE USE THE MAIN CONFIG TO SPECIFY BLOCKLIST PATHS AND CURATED CONFIG PATHS.

  • hardcoded_blocklist_path: Embeds a path to a blocklist into Bazaar which, if possible, will always be read with highest priority.
  • hardcoded_content_config_path: Embeds a path to a curated YAML configuration file into Bazaar which, if possible, will always be read with highest priority

Curated Configurations

If Bazaar is provided a non-zero amount of curated configs, an extra tab will appear on the window’s header bar called “Curated”. This section is intended for distributors to curate applications for users with a customizable interface. Curated configs are YAML files. They are constantly monitored by Bazaar for filesystem events, so when the config changes, Bazaar will automatically reload the content.

Right now, curated configs are essentially composed of a list of “sections” which appear stacked on top of each other inside of a scrollable viewport in the order they appear in the YAML. Each section has certain properties you can customize, like a title, an image banner URI, and of course a list of appids. Bazaar maps the appids you provide to the best matching “entry group” from the table of applications it was able to pull from remote sources (Simply put, an entry group in Bazaar is a collection of applications which share the same appid but come from different sources or installations). The entry group has a designated “ui entry” which was previously determined in the refresh process to have the most useful content associated with it as it pertains to presenting things like icons, descriptions, screenshots, etc to the user. When the user selects the app in the section, they are brought to a “full view” where they can see a bunch of information stored inside or referenced by the ui entry and choose to invoke transactions on the entry group, like installation or removal.

Additionally, curated configs allow you to define a css block from which you can reference classes inside sections and change the way gtk renders the content.

Here is a basic curated config:

# Some css names at your disposal:
# - banner
# - banner-text
# - banners
# - description
# - subtitle
# - title
# - app-tile
# - app-tile-title
# - app-tile-verified-check
# - app-tile-description
css: |
  .main-section {
    margin: 15px;
    border-radius: 25px;
  }
  .main-section banner-text {
    margin: 15px;
    color: white;
  }
  .background-1 {
    background: linear-gradient(45deg, #170a49, #52136c);
  }
  .background-1 title {
    border-bottom: 5px solid white;
  }
  .background-1 app-tile > button {
    background-color: alpha(white, 0.1);
  }
  .background-1 app-tile > button:hover {
    background-color: alpha(var(--accent-bg-color), 0.5);
  }
  .background-2 {
    background: linear-gradient(75deg, #51263c, #7104a9);
  }
  .background-2 app-tile > button:focus {
    background-color: alpha(var(--accent-bg-color), 0.5);
  }
  .background-2 app-tile-verified-check {
    color: orange;
  }

rows:
  - sections:
    - expand-horizontally: true

      category:
        title: "My Favorite Apps"
        subtitle: "These are really good and you should download them!"

        # can be https as well
        banner: file:///home/kolunmi/banner-1.jxl

        # can be "fill", "contain", "cover", or "scale-down"
        # see https://docs.gtk.org/gtk4/enum.ContentFit.html
        banner-fit: contain

        # can be "fill", "start", "end", or "center"
        # see https://docs.gtk.org/gtk4/enum.Align.html
        # halign -> "horizontal alignment"
        banner-text-halign: start
        # valign -> "vertical alignment"
        banner-text-valign: center

        # "The horizontal alignment of the label text inside its size
        # allocation."
        # see https://docs.gtk.org/gtk4/property.Label.xalign.html
        banner-text-label-xalign: 0.0

        # appid list
        appids:
          - com.usebottles.bottles
          - io.mgba.mGBA
          - net.pcsx2.PCSX2
          - org.blender.Blender
          - org.desmume.DeSmuME
          - org.duckstation.DuckStation
          - org.freecad.FreeCAD

      # reference the classes we defined earlier
      classes:
        - main-section
        - background-1

      # The `classes` key (above) is for styling which we want to apply
      # all the time. If you want a style class to only be active in
      # light or dark mode, use `light-classes` or `dark-classes`:
      light-classes:
        - light-section
      dark-classes:
        - dark-section


  - sections:
    - category:
        title: "Some more awesome apps!"
        subtitle: "These are also pretty cool"
        banner: file:///home/kolunmi/banner-2.png
        banner-fit: contain
        banner-text-halign: end
        banner-text-valign: center
        banner-text-label-xalign: 1.0
        appids:
          - org.gimp.GIMP
          - org.gnome.Builder
          - org.gnome.Loupe
          - org.inkscape.Inkscape
      classes:
        - main-section
        - background-2

Blocklists

Blocklists are a way to ensure that users will never interact with a certain application inside Bazaar. There are two kinds of blocklists supported by Bazaar:

YAML files, containing special rules, priorities, and regex:

blocklists:
  - priority: 0
    block-regex:
      # block all ids matching this regex unconditionally
      - com\.place\..*
  - priority: -1 # lower number = higher priority
    conditions:
      - match-locale:
          # only apply this rule if we have the Arabic locale
          regex: ar
    allow:
      - com.place.App3
      - com.place.App5
    allow-regex:
      - com\.place\..*\.ar
  - priority: -1
    conditions:
      - match-locale:
          regex: en.*
        # invert the result of this condition; so all locales which don't match
        # the regex
        post-process: invert
      - match-envvar:
          var: PATH
          regex: .*/usr/local/bin.*
    block:
      - com.other.App1
    allow:
      - com.place.App1
      - com.place.App2

Simple plain text files with newline-separated appids:

com.jetbrains.CLion
com.valvesoftware.Steam
io.neovim.nvim
net.lutris.Lutris

Note: blocklists will only prevent certain appids from appearing in Bazaar. They do not stop the user from installing anything with the flatpak cli, for example.

Hooks

Hooks are an advanced feature of Bazaar. In essence, they allow you to programmatically react to events and define dialogs with which you can query user input. Currently, the only events you can subscribe to are the “before-transaction” and “after-transaction” events:

  • before-transaction: run the hook right before a transaction is scheduled to begin
  • after-transaction: run the hook after a transaction successfully completes

Hooks are run like a signal emission. After an event occurs, hooks that are found to be of the appropriate type are evaluated in an order of priority. Higher priority hooks have the ability to stop the emission from propagating further downwards. In the case of some events, like “before-transaction”, a hook can also hint to Bazaar some action to take, in this case whether the transaction should be aborted.

A shell snippet which is defined by you is evaluated with /bin/sh -c multiple times over the course of a hook’s execution. An invocation of the shell snippet is referred to as a “stage”. Your shell snippet (which of course could just invoke another script written in whatever language you prefer) will be provided a number of environment variables which together will describe the current stage. Your snippet must react accordingly by printing a response to stdout, which Bazaar will read back.

This opens up a lot of possibilities for customization; here are a few examples:

  • You would like a certain appid to be added to steam after the user installs it, so you register a hook on “after-transaction” to query the user’s permission with a custom dialog. If they confirm, your script will go forward with the task of setting up a steam shortcut.
  • You would like to prevent users from installing a certain appid, as some other method of installation, such as a system package, would provide a superior experience. A blocklist could achieve this, but you don’t like the idea of hiding anything from the user. A hook subscribed to the “before-transaction” event could issue a warning and ask for extra confirmation. If the user decides to listen to the warning, you can signal to Bazaar that the transaction should be aborted.

Here is an overview of the environment variables the shell snippet will receive:

  • BAZAAR_HOOK_INITIATED_UNIX_STAMP: the unix timestamp in seconds at which this hook was first invoked (the number of seconds that have elapsed since 1970-01-01 00:00:00 UTC)
  • BAZAAR_HOOK_INITIATED_UNIX_STAMP_USEC: the unix timestamp in microseconds at which this hook was first invoked (the number of microseconds that have elapsed since 1970-01-01 00:00:00 UTC)
  • BAZAAR_HOOK_STAGE_IDX: the number of stages this hook has run so far
  • BAZAAR_HOOK_ID: the value of the “id” mapping
  • BAZAAR_HOOK_TYPE: the value of the “when” mapping
  • BAZAAR_HOOK_WAS_ABORTED: “true” if a dialog aborted the hook
  • BAZAAR_HOOK_DIALOG_ID: if applicable, the id of the current dialog
  • BAZAAR_HOOK_DIALOG_RESPONSE_ID: if applicable, the user response given through the current dialog
  • BAZAAR_TS_APPID: if applicable, the appid of the entry Bazaar is currently dealing with
  • BAZAAR_TS_TYPE: if applicable, the type of transaction being run. Can be “install”, “update”, or “removal”.
  • BAZAAR_HOOK_STAGE: the stage at which the hook is running. This will indicate what the shell body is instructed to do at this time. The shell body must respond by outputting to stdout with a valid answer; the structure of a valid answer will depend on the stage, and if the structure is not valid the hook will be abandoned. The shell body might be run multiple times by Bazaar over the course of a hook with this variable set to differing values in order know how to orchestrate events in the UI, so the shell body must be able to branch depending on the value. The value may be any of the following:
    • setup: the hook is starting. Respond with “ok” to continue the execution of this hook, or “pass” to skip it and move on to the next registered hook
    • setup-dialog Bazaar is ready to ask the user a question with one of the dialogs you’ve defined inside the “dialogs” mapping. BAZAAR_HOOK_DIALOG_ID will tell you which one. Respond with “ok” to spawn the dialog, or “pass” to skip the dialog.
    • teardown-dialog Bazaar has received input from the user after asking them a question with one of the dialogs you’ve defined inside the “dialogs” mapping. BAZAAR_HOOK_DIALOG_ID will tell you which one. BAZAAR_HOOK_DIALOG_RESPONSE_ID will tell you the response the user chose. Respond with “ok” to continue, or “abort” to stop the execution of this hook.
    • catch One of your dialogs has aborted. This is your chance to handle the error. Respond with “recover” to continue, or “abort” to confirm that the execution of this hook should indeed skip to the teardown stage.
    • action Everything so far has gone according to plan, so it is time to take whatever external action this hook exists for. Bazaar requires no response at this time.
    • teardown The hook is cleaning up. Respond with “continue” to propagate the signal emission to lower priority hooks, or “stop” to indicate the emission should stop. Alternatively, if this hook type should hint to Bazaar an action to take (such as the “before-transaction” hook), respond with “confirm” to hint that the action should be taken, or “deny” to prevent the action from being taken. Both “confirm” and “deny” imply the effect of “stop”, and “stop” implies “confirm”.

Hooks are defined in the main yaml config as indicated by the hardcoded_main_config_path comptime var. Here is a basic example demonstrating how to define a hook:

yaml-blocklist-paths:
  - /path/to/yaml/blocklist.yaml
  - /path/to/another/yaml/blocklist.yaml
txt-blocklist-paths:
  - /path/to/txt/blocklist.txt
  - /path/to/another/txt/blocklist.txt
curated-config-paths:
  - /path/to/yaml/file.yaml
  - /path/to/another/yaml/file.yaml

hooks:
  - id: my-hook
    when: before-transaction
    dialogs:
      - id: my-dialog-1
        title: "Please confirm"
        # If true, render inline markup commands
        # see https://docs.gtk.org/Pango/pango_markup.html
        body-use-markup: true
        body: "This application is an official <a href=\"https://www.gnome.org/\">GNOME</a> app, which is <b>important</b> because..."
        # Determines which option will be assumed if the user hits the
        # escape key or otherwise cancels the dialog
        default-response-id: no
        options:
          - id: no
            string: "Don't install"
            # can be "destructive" or "suggested" or omit for no
            # styling
            style: destructive
          - id: yes
            string: "Next"
            style: suggested
      - id: my-dialog-2
        title: "Double check"
        body-use-markup: false
        body: "Here are some other considerations..."
        default-response-id: no
        options:
          - id: no
            string: "Don't install"
            style: destructive
          - id: yes
            string: "Continue with install"
            style: suggested
    shell: |
      case "$BAZAAR_HOOK_STAGE" in
          setup)
              if [ "$BAZAAR_TS_TYPE" = install ]; then
                case "$BAZAAR_TS_APPID" in
                    org\.gnome\.*)
                        echo 'ok' ;;
                    *) echo 'pass' ;;
                esac
              else
                echo 'pass'
              fi
              ;;
          setup-dialog)
              echo 'ok'
              ;;
          teardown-dialog)
              case "$BAZAAR_HOOK_DIALOG_RESPONSE_ID" in
                  yes) echo 'ok' ;;
                  *) echo 'abort' ;;
              esac
              ;;
          catch)
              echo 'abort'
              ;;
          action)
              ;;
          teardown)
              [ "$BAZAAR_HOOK_WAS_ABORTED" = true ] && echo 'deny' || echo 'confirm'
              ;;
      esac

In this example, if this user tries to install an appid that starts with org.gnome., we present two dialogs asking for confirmation. If they decide to select a response with an id other than yes, abort the transaction.

More realistic example

hardcoded_main_config_path:

hooks:
  - id: handle-jetbrains
    when: before-transaction
    dialogs:
      - id: jetbrains-warning
        title: >-
          Jetbrains IDEs are not supported in this format
        # If true, render inline markup commands in body; see
        # https://docs.gtk.org/Pango/pango_markup.html
        body-use-markup: true
        body: >-
          This is a <a href="https://www.jetbrains.com/">Jetbrains</a>
          application and is not officially supported on Flatpak. We
          recommend using the Toolbox app to manage Jetbrains IDEs.
        # Determines which option will be assumed if the user hits the
        # escape key or otherwise cancels the dialog
        default-response-id: cancel
        options:
          - id: cancel
            string: "Cancel"
          - id: goto-web
            string: "Download Jetbrains Toolbox"
            # can be "destructive" or "suggested" or omit for no
            # styling
            style: suggested
    shell: exec /absolute/path/to/bazaar-jetbrains-hook.bash

/absolute/path/to/bazaar-jetbrains-hook.bash:

#!/usr/bin/env bash


handle_setup_stage() {

    # only proceed if the user is installing something
    if [ "$BAZAAR_TS_TYPE" = install ]; then
        case "$BAZAAR_TS_APPID" in
            com\.jetbrains\.*)
                # since the appid belongs to jetbrains, we continue
                # with the hook
                echo 'ok'
                ;;
            *)
                # otherwise, skip this hook
                echo 'pass'
                ;;
        esac
    else
        echo 'pass'
    fi

}


handle_setup_dialog_stage() {

    # we don't need to do anything here right now, just let Bazaar
    # know we should continue setting up the dialog
    echo 'ok'

}


handle_teardown_dialog_stage() {

    case "$BAZAAR_HOOK_DIALOG_RESPONSE_ID" in
        goto-web)
            # if the user pressed "Download Jetbrains Toolbox",
            # continue
            echo 'ok'
            ;;
        *)
            # otherwise, let's not do anything
            echo 'abort'
            ;;
    esac

}


handle_catch_stage() {

    # this only happens if the `teardown-dialog` stage echoed "abort",
    # we could echo "recover" at this point to still go to the
    # `action` stage, but we have no reason to do that right now
    echo 'abort'

}


handle_action_stage() {

    # this is where we do the thing! it is important to use `nohup`
    # here so bazaar doesn't hang
    nohup xdg-open 'https://www.jetbrains.com/toolbox-app/'

}


handle_teardown_stage() {

    # Let's always prevent the user from installing Jetbrains stuff
    echo 'deny'

}


# Branch based on the stage
case "$BAZAAR_HOOK_STAGE" in
    setup) handle_setup_stage ;;
    setup-dialog) handle_setup_dialog_stage ;;
    teardown-dialog) handle_teardown_dialog_stage ;;
    catch) handle_catch_stage ;;
    action) handle_action_stage ;;
    teardown) handle_teardown_stage ;;
esac


# exit successfully
exit 0