docs: tutorial/example for ngclient Updater

EDIT: I think starting with out-of-the-box runnable example code is a better idea: see comment below (original issue follows:)

the updater module docs show how to write a client in five lines of code but they also mention dependencies:

    * A webserver running on http://localhost:8000, serving TUF repository
      metadata at "/tuf-repo/" and targets at "/targets/"
    * Local metadata directory "~/tufclient/metadata/" is writable and contains
      a root metadata version for the remote repository
    * Download directory "~/tufclient/targets/" is writable

would be nice to have really easy to follow instructions that handle all of that…

The tutorial should live within the documentation but not in the ngclient module docs, just as a page on its own. Actually writing the tutorial is probably a “good first issue”?

[kairoaraujo]

Before submitting the PR, I am sending a design proposal/draft for local static server

The idea is to start with a simple document describing how to run an example of a client code using the ngclient and the static metadata from tests/repository_data/repository/.

The document will have three basic steps.

1. Run the HTTP Server using the tests data repository
2. How to initialize the client to prepare the client infrastructure
3. Download files to show different scenarios In that step, we will highlight the TUF/ngclient behaviors.

The client code example:

• The example will be stored inside the examples/ in the root folder. The reason is that some people check examples, even before the documentation.

• The idea is a commented code, including references to the API and/or the Specification.

• The initial name suggested will be client_example as a small Python Command Line Interface (CLI) executable/script.

  • The metadata repository directory will be in $HOME/.local/share/<app-name-here>/
  • The download folder directory will be in download (local directory)

• The example will be a simple CLI with initial two parameters:

  • --init
    This parameter will create the client’s infrastructure, the metadata folder (including the initial root.json), and the download folder. Running this example will be explicit about all the steps. The CLI will print the messages.

  ./client_example --init
  [INFO] metadata folder [<path>] created.
  [INFO] Bootstrap 'root.json' with a trusted source.
  [INFO] Download folder  ['downloads'] created.
  [INFO] Client initialization finished.
  

  The second scenario is the client already initialized, but the messages above will be the same.

  • --download <filename>. Along with the how-to documentation, the instruction will be to download different targets. The goal is to demonstrate flow, the terminology used in the framework, using the steps messages (printing as log), such as:

  ./client_example --download file.txt
  [INFO] Updating metadata from remote.
  [INFO] Getting target info.
  [INFO] Checking if the target <name> is cached.
  [INFO] Downloading target <name> to download <path name>.
  [INFO] File downloaded successfully.
  

[kairoaraujo]

I’m picking up this issue.