Capture discussion around the purpose of the reference implementation.
That we prioritise being an exemplary implementation over being a
pedagogical implementation.
Signed-off-by: Joshua Lock <jlock@vmware.com>
For targetpath: we don't want to support corner cases such as
file paths starting with separator.
Why this case should be threated specially than any other case where
you have multiple "/" for example "foo//bar/tar.gz"?
For pathpattern: it's recommended that the separator in the pathpattern
should be "/":
see https://theupdateframework.github.io/specification/latest/#targetpath
I believe it could lead to issues for a client implementation if it
supports arbitrary separators - every implementation needs to choose one
and stick with it.
Then, if we decide that "/" is our separator using lstrip on "os.sep" is
wrong, because the os separator from the server could be different that
the one used in the client.
Because of the above arguments, it makes sense to just remove
lstrip on os separators.
Additionally, document that the target_filepath and the DelegatedRole
paths are expected to be in their canonical forms and only "/" is
supported as target path separator.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
in the public API that we only support "/" as a
separator and don't handle corner cases such as leading separators
in either pathpattern or target_filepath.
If a file has a bigger size than expected, RequestFetcher.fetch
downloads it up to max_length without any errors. Only the
consecutive hash check raises exception. A better behaviour
in such case would be to raise a DownloadLengthMismatchError.
For this reason this commit:
- removes max_length from the fetch() definition,
- modifies download_file to check the downloaded length after
each chunk and raise an error accordingly.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
Add an additional private method for loading the initial
trusted root metadata. The public method update_root() is
now used only externally for updating the intiial root.
The 'root' property is used only after its initialization
in the constructor and is not longer optional which makes
mypy happy.
This split results in cleaner code and the ability to annotate
the 'root' property as non-optional at the cost of some code
duplication.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
By explicitly denoting the expected type of Metadata.signed
we help mypy understand our intentions and correctly figure
out types. This is entirely a typing feature and has no
runtime effect.
Modify the return type of Metadata.from_dict to match the
other factory methods (from_*).
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
SlowRetrievalError is raised from RequestsFetcher where
average_download_speed is not calculated.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
This is done only for hinting 'mypy' that we have
ensured these values cannot be None.
'Bandit' raises warnings for assert usage in the code
but we are disabling them since we do not rely upon
'asserts' for any runtime checks but only for type checking.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
Needed in order to be compatible with the return type of
download_file (TemporaryFile is typed as IO[bytes]).
BinaryIO is a subclass of IO[bytes].
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
Add the stub for the requests package (types-requests)
to requirements-tests.txt.
Add urllib3 to the ignored imports. The project seems
to have added type annotations already but has not
released a version including them yet.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
According to the recently updated version of the specification the shell
style wildcard matching is glob-like (see https://github.com/theupdateframework/specification/pull/174),
and therefore a path separator in a path should not be matched by a
wildcard in the PATHPATTERN.
That's not what happens with `fnmatch.fnmatch()` which doesn't
see "/" separator as a special symbol.
For example: fnmatch.fnmatch("targets/foo.tgz", "*.tgz") will return
True which is not what glob-like implementation will do.
We should make sure that target_path and the pathpattern contain the
same number of directories and because each part of the pathpattern
could include a glob pattern we should check that fnmatch.fnmatch() is
true on each target and pathpattern directory fragment separated by "/".
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
After the addition of "path" argument in the TargetFile class the
filename argument in Targets.update() became redundant.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
Currently, TargetFile instances do not contain the path relative URL of
the file they represent. The API itself does not need it but it could be
useful for users of the API.
As an example, the current client returns a dict for
get_one_valid_targetinfo(): that dict contains a filepath field and
a targetinfo field (essentially TargetFile).
We would like to keep a similar API, but avoid hand-crafted dicts.
It would be much nicer to return a TargetFile that would contain the
full "metadata" of the targetfile.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
The securesystemslib key dictionary representation includes
the private key in keyval. TUF key doesn't handle it in any way,
but considering that we allow unrecognized symbols in the format,
we should exclude the private key otherwise this could lead to
misuse.
A call to securesystemslib.keys.format_keyval_to_metadata
with the default private=False would do exactly that.
Signed-off-by: Velichka Atanasova <avelichka@vmware.com>
Improve class DelegatedRole docstring in order to be rendered
correctly in the documentation built with sphinx and autodoc.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
pip nowadays recognizes that we are asking for two different versions of
securesystemslib in the "with-sslib-master" env, and errors out.
Instead install normal dependencies first, then install the new
securesystemslib separately (this ends up upgrading securesystemslib).
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
Write a bit more about the two modules, hide the actual TOC to not
repeat (and not have sphinx complain about missing items in TOC)
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
This allows using existing documentation in the published documentation
without
* moving the existing docs (which would break external links)
* tricks like symlinks that create issues with relative links
Put the api reference files into a subdirectory to avoid polluting the
main docs/ directory.
Include "Installation" and "Instructions for Contributors" in the
published documentation.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
* Remove link to outdated roadmap
* Link to maintainers file in the same way as two lines earlier
* Fix formatting issues with code blocks
These fixes allow the installation rst to be used from sphinx sources
and from docs root.
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
* Improve content
* Make ngclient Updater __init__() visible in docs
* Remove "legacy implementation" (except for the note on API stability)
Signed-off-by: Jussi Kukkonen <jkukkonen@vmware.com>
I was looking at how can we simplify or split test_api.py when I noticed
that the test cases covered by those two test functions are already
covered in the test_metadata_serialization.py module in the
"invalid_keys" and "invalid_roles" datasets.
Signed-off-by: Martin Vrachev <mvrachev@vmware.com>
- New 'docs' environment in tox enables
building the sphinx documentation in isolation.
- New requirements-docs.txt.
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
Add .rst source files for building documentation with
'sphinx'. The two mandatory files are conf.py containing
the build configuration and the master doc file index.rst.
Sphinx uses 'autodoc' to automatically include docstrings.
'autodoc' imports the modules and needs TUF installed in
the environment.
The following command will generate the documentation from the
source files in an html format:
`sphinx-build -b html docs/sphinx/source docs/sphinx/build/html`
Signed-off-by: Teodora Sechkova <tsechkova@vmware.com>
