Skip to content

Commit 563bb41

Browse files
committed
Update TARGETPATH and PATHPATTERN recommendations
In addition to recommending the omission of leading directory separators, this commit adds a recommendation for forward slashes as preferred directory separators in TARGETPATH and PATHPATTERN. The rationale is that a TARGETPATH needs to be concatenated with a mirror's base URL, and as such it might yield unexpected behavior with non standardized paths. Same goes for Unix shell-style pattern matching of target paths using PATHPATTERN. As suggested by @erickt this commit adds a reference to the "path-relative-URL string" definition from the WHATWG URL spec as the preferred TARGETPATH style. This commit also switches to using the term "directory separator" instead of the prior used "path separator" to disambiguate from characters that separate paths (e.g. colon on Unix).
1 parent 6c6eb9d commit 563bb41

File tree

1 file changed

+12
-5
lines changed

1 file changed

+12
-5
lines changed

tuf-spec.md

Lines changed: 12 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -806,9 +806,13 @@ repo](https://github.com/theupdateframework/specification/issues).
806806
}
807807

808808
Each key of the TARGETS object is a TARGETPATH. A TARGETPATH is a path to
809-
a file that is relative to a mirror's base URL of targets. It should not
810-
have a leading path separator to avoid surprising behavior when constructing
811-
paths on disk.
809+
a file that is relative to a mirror's base URL of targets. To avoid
810+
surprising behavior when resolving paths, it is RECOMMENDED that a
811+
TARGETPATH uses the forward slash (/) as directory separator and does not
812+
start with a directory separator. The recommendation for TARGETPATH aligns
813+
with the ["path-relative-URL string"
814+
definition](https://url.spec.whatwg.org/#path-relative-url-string) in the
815+
WHATWG URL specification.
812816

813817
It is allowed to have a TARGETS object with no TARGETPATH elements. This
814818
can be used to indicate that no target files are available.
@@ -881,8 +885,11 @@ repo](https://github.com/theupdateframework/specification/issues).
881885
match file paths "targets/foo.tgz" and "targets/bar.tgz", but not
882886
"targets/foo.txt". Likewise, path pattern "foo-version-?.tgz" matches
883887
"foo-version-2.tgz" and "foo-version-a.tgz", but not "foo-version-alpha.tgz".
884-
It should not have a leading path separator to avoid surprising behavior when
885-
constructing paths on disk.
888+
To avoid surprising behavior when matching targets with PATHPATTERN, it is
889+
RECOMMENDED that PATHPATTERN uses the forward slash (/) as directory
890+
separator and does not start with a directory separator, akin to
891+
TARGETSPATH.
892+
886893

887894
Prioritized delegations allow clients to resolve conflicts between delegated
888895
roles that share responsibility for overlapping target paths. To resolve

0 commit comments

Comments
 (0)