Interface version canonicalization

[lann]

See #534

• I stuck fullversion in the import/export productions rather than interfacename because I wanted it to be clear that it wouldn't be lowered into the core name.
• The version canonicalization rules are adapted from Add BuildTargets.md #378. I'm still leaning toward omitting prerelease versions but I've only thought "medium hard" about it.
• Still needs binary encoding; see comment below.
• Not sure how best to capture the discussion about making canonicalization mandatory pre-1.0; the "Binary Warts" section doesn't seem quite right.

[lann]

For the binary encoding the most straightforward option from a quick review would seem to be adding variants of importname' / exportname' along the lines of:

importname' ::= 0x00 len:<u32> in:<importname>                       => in  (if len = |in|)
              | 0x01 len:<u32> in:<importname> fullverlen:<u16> fullver:<valid semver>

I suppose if we wanted to optimize the binary a bit this extra field could contain just the part of the original version that got lopped off by canonicalization.

On this field width:

fullverlen:<u16>

https://semver.org/#does-semver-have-a-size-limit-on-the-version-string

No, but use good judgment. A 255 character version string is probably overkill, for example. Also, specific systems may impose their own limits on the size of the string.

🤷

[lukewagner]

@lann Thanks for starting this! For the binary encoding question: yes, taking over the 0x00 byte and using it as a discriminant is a nice coincidence we can take advantage of (and could you update the corresponding bullet in the "Warts" section at the end)?

I suppose if we wanted to optimize the binary a bit this extra field could contain just the part of the original version that got lopped off by canonicalization.

Is there a simplicity argument to be made that requiring the concatenation of the version and the fullversion to match <valid semver> is simpler than allowing the fullversion to be <valid semver> and then adding the additional validation requirement (which I assume we want) that the fullversion has to "match" the version? If so, that could be a second argument in favor in addition to size.

[lukewagner]

Looking good! A few drive-by comments:

[lukewagner]

Suggested change

	fullversion ::= (fullversion <valid semver>)
	fullversion ::= (fullversion "<valid semver>")

[lukewagner]

Suggested change

	inlineexport ::= (export <exportname> <fullversion>? <sortidx>)
	inlineexport ::= (export "<exportname>" <fullversion>? <sortidx>)

(pre-existing, but since we're touching this line)

[lukewagner]

Suggested change

	importdecl ::= (import <importname> <fullversion>? bind-id(<externdesc>))
	exportdecl ::= (export <exportname> <fullversion>? bind-id(<externdesc>))
	importdecl ::= (import "<importname>" <fullversion>? bind-id(<externdesc>))
	exportdecl ::= (export "<exportname>" <fullversion>? bind-id(<externdesc>))

[lukewagner]

(pre-existing)

[lukewagner]

Could you frame "canonicalized interface version" as a validation rule factored out into a new "Canonical Interface Name" section alongside and symmetric to "Name Uniquness" and say that it is temporarily not enforced but will start issuing warnings and be enforced post-Preview-3?

[lukewagner]

Probably good to rename this interfaceversion since it's specific to interfacename (and to be symmetric to pkgversion). (I know that'll mess up the column alignment and fixing bloats the diff obscuring the change; maybe leave it unaligned and fix it right before merging.)

[lukewagner]

(oops, meant to "comment" not approve before it's even ready to review 🙃 )

[alexcrichton]

For the binary encoding, here's another possible encoding:

importname' ::= 0x00 len:<u32> in:<importname>                       => in  (if len = |in|)
              | 0x01 len:<u32> in:<importname>                       => "${in.name}@N"  (if len = |in|,  in.version = N.*)
              | 0x02 len:<u32> in:<importname>                       => "${in.name}@0.N"  (if len = |in|,  in.version = 0.N.*)
              | 0x03 len:<u32> in:<importname>                       => "${in.name}@0.0.N"  (if len = |in|,  in.version = 0.0.N.*)

maybe with affordances for rc/etc unsure. The basic idea though is that the actual import name would always be foo:bar/baz@0.1.2 in the binary format but the semantic meaning (e.g. the text format) would be a subslice of such a string. This codifies that in the binary format it's always a valid semver and the discriminant byte says basically how to shorten it. The goal here would be to make the binary format still pretty clear what it can be without changing the meaning of the meaning at a parsed layer.

fullverlen:

https://semver.org/#does-semver-have-a-size-limit-on-the-version-string

No, but use good judgment. A 255 character version string is probably overkill, for example. Also, specific systems may impose their own limits on the size of the string.

For this I'd recommend using <u32> regardless. We already limit many strings far below the theoretical 4G limit with a 32-bit length and keeping <u32> makes it more consistent with the rest of the decoding process. Otherwise when implementing a decoder you'd have to implement a specific function for decoding a 16-bit LEB which is otherwise not required when parsing WebAssembly today. Basically while I agree that >255 characters for a version is silly, I'd say that for consistency with the rest of the binary format this'd want to be <u32> if we go with this variant.