From 7b593f3fdbb472c233402ed6ebaf64f1f34f2da5 Mon Sep 17 00:00:00 2001 From: Jussi Kukkonen Date: Wed, 23 Mar 2022 10:06:03 +0200 Subject: [PATCH] docs: Add doc links to ngclient blog post Signed-off-by: Jussi Kukkonen --- docs/_posts/2022-03-22-ngclient-design.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/_posts/2022-03-22-ngclient-design.md b/docs/_posts/2022-03-22-ngclient-design.md index 627cb333..b4dfcbf5 100644 --- a/docs/_posts/2022-03-22-ngclient-design.md +++ b/docs/_posts/2022-03-22-ngclient-design.md @@ -9,13 +9,13 @@ We recently released a new TUF client implementation, `ngclient`, in Python-TUF. The legacy code had a few problems that could be summarized as non-optimal abstractions: Significant effort had been put to code re-use, but not enough attention had been paid to ensure the expectations and promises of that shared code were the same in all cases of re-use. This combined with Pythons type ambiguity, use of dictionaries as "blob"-like data structures and extensive use of global state meant touching the shared functions was a gamble: there was no way to be sure something wouldn't break. -During the redesign, we really concentrated on finding abstractions that fit the processes we wanted to implement. It may be worth mentioning that in some cases this meant abstractions that have no equivalent in the TUF specification: some of the issues in the legacy implementation look like the result of mapping the [_specifications Detailed client workflow_](https://theupdateframework.github.io/specification/latest/#detailed-client-workflow) directly into code. +During the redesign, we really concentrated on finding abstractions that fit the processes we wanted to implement. It may be worth mentioning that in some cases this meant abstractions that have no equivalent in the TUF specification: some of the issues in the legacy implementation look like the result of mapping the TUF specifications [_Detailed client workflow_](https://theupdateframework.github.io/specification/latest/#detailed-client-workflow) directly into code. -Here are the core abstractions we ended up with (number of lines of code in parenthesis to provide a bit of context): -* `Metadata` (800 SLOC) handles everything related to individual pieces of TUF metadata: deserialization, signing, and verifying +Here are the core abstractions we ended up with (number of lines of code in parenthesis to provide a bit of context, alongside links to sources and docs): +* `Metadata` (800 SLOC, [docs](https://theupdateframework.readthedocs.io/en/latest/api/tuf.api.html)) handles everything related to individual pieces of TUF metadata: deserialization, signing, and verifying * `TrustedMetadataSet` (170 SLOC) is a collection of local, trusted metadata. It defines rules for how new metadata can be added into the set and ensures that metadata in it is always consistent and valid: As an example, if `TrustedMetadataSet` contains a targets metadata, the set guarantees that the targets metadata is signed by trusted keys and is part of a currently valid TUF snapshot -* `Updater` (250 SLOC) makes decisions on what metadata should be loaded into `TrustedMetadataSet`, both from the local cache and from a remote repository. It handles persisting validated metadata and targets onto local storage and provides the user-facing API -* `FetcherInterface` (100 SLOC) is the abstract file downloader. By default, a Requests-based implementation is used but clients can use custom fetchers to tweak how downloads are done +* `Updater` (250 SLOC, [docs](https://theupdateframework.readthedocs.io/en/latest/api/tuf.ngclient.updater.html)) makes decisions on what metadata should be loaded into `TrustedMetadataSet`, both from the local cache and from a remote repository. While `TrustedMetadataSet` always raises an exception if a metadata is not valid, `Updater` considers the context and handles some failures as a part of the process and some as actual errors. `Updater` also handles persisting validated metadata and targets onto local storage and provides the user-facing API +* `FetcherInterface` (100 SLOC, [docs](https://theupdateframework.readthedocs.io/en/latest/api/tuf.ngclient.fetcher.html)) is the abstract file downloader. By default, a Requests-based implementation is used but clients can use custom fetchers to tweak how downloads are done No design is perfect but so far we're quite happy with the above split. It has dramatically simplified the implementation: The code is subjectively easier to understand but also has significantly lower code branching counts for the same operations.