theupdateframework / theupdateframework/specification

consistent targets is not well defined with regards to TARGETPATH

Open
#183 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

question
Dominant language
Python
Stars
405
Forks
59
Avg merge
3d 4h
Merged PRs (30d)
1

Description

When the specification talks about consistent targets, it always refers to filenames. Here is 6.2.1. Writing consistent snapshots:

consistent target files should be written to non-volatile storage as digest.filename.ext

Here is 5.7.3 talking about building the download URL in client:

the filename is of the form HASH.FILENAME.EXT

The issue is that in both cases what we are really interested in is the target path (which is really part of a target URL) and how the hash is used produce the target URL (on client) or how it is parsed from a target URL (on repository). The spec should define how to do URL construction instead of defining filename construction.

https://theupdateframework.github.io/specification/latest/#targetpath does limit target path to just URL path segments (so according to that query and fragment parts would not be allowed in target path).

So:

  • Injecting hash into and parsing the hash from target URL should be defined instead of talking about filenames
  • if the valid target paths are restricted by spec, those restrictions should be stated (e.g. must a filename part be non-empty?)
  • Preferably examples should be given

Some potential target path examples:

a
a/b
a%2Fb
a\b
a/
?a=b        # query, so not allowed according to strictest targetpath definition
#a          # fragment, so not allowed according to strictest targetpath definition

In all of these cases we can figure out a "filename like component" (in last 3 the filename is an empty string) and we can of course prefix that with {HASH}.. Alternatively the spec could require the target path to contain a non-empty filename element ("filename" is not a thing that really exists in URLs but I assume we could).

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with specification sections 5.7.3, 6.2.1, and the targetpath definition referenced in the issue. Compare their filename and target-path language, then update the specification to define hash handling, valid target-path restrictions, and representative examples consistently.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.