provide special ".local" module name to be used for local-only modules

[rogpeppe]

Currently cue mod init uses the module path cue.example by default.

This is problematic for a few reasons:

• it's totally arbitrary, and not obviously "local"
• local modules often aren't "examples"
• people can inadvertently publish such modules to a registry, giving rise to the possibility of namespace conflicts.

We propose that a special module path, .local is used for this instead.

This is:

• much more clearly local-only
• can easily be distinguished and denied when publishing to a registry
• does not have any specific connotations other than the fact it's not remote

For #3620.

[mvdan]

For the sake of completeness, RFC 2606 reserves .test, .example, .invalid, and .localhost for the sake of testing and documentation, and RFC 6762 reserves .local for the sake of local host names which could be resolved. Which seems like a relatively short version of .localhost.

I think it would make sense for us to consistently treat all five of the above as local-only module TLDs as you describe. Doing only one, but not the others, feels a bit odd. I think our examples could then use .example, our tests could use .test, and our defaults such as cue mod init could use .local.

The only quirk is whether, per RFC 6762, treating .local as meaning just the local machine is OK. It seems like it could also be interpreted to mean "the local network", meaning it cannot get out to the internet, but can still be used for service discovery across the local network.

[mvdan]

It's also worth noting that Go did this by reserving the module prefixes (not TLDs!) example and test, so e.g. test/foo but not foo.test/bar. See https://go.dev/ref/mod#module-path. I prefer the approach suggested here, because the TLDs follow well established RFCs.

[btrepp]

To throw some things in, cue actually supports this by doing subdomains of localhost.
I've started going 'module.localhost' to defer the idea of a module I won't really 'publish', so just need some identifier that plays with cue. This is valid and use-able now, and I don't have to think 'do I need to buy a domain name to use cue'

It also aligns with the definitions of https://datatracker.ietf.org/doc/html/rfc6761#section-6.3
and works properly with nslookup (which is not necessary, but kinda nice?)

nslookup cueproject.localhost
Server:         192.168.65.7
Address:        192.168.65.7:53

Non-authoritative answer:
Name:   cueproject.localhost
Address: 127.0.0.1

Non-authoritative answer:
Name:   cueproject.localhost
Address: ::1

So there is the option that rather than special names, perhaps just the default namespacing that way, and documentation supporting it may be helpful.

Perhaps even cue mod init, rather than generate 'cue.example', can use the folder and local host.

Eg if the default could be like running this

cue mod init $(basename $PWD).localhost

That would help newcomers avoid the 'choosing names when I don't know the significance is hard' problem.

For the sake of completeness, RFC 2606 reserves .test, .example, .invalid, and .localhost for the sake of testing and documentation, and RFC 6762 reserves .local for the sake of local host names which could be resolved. Which seems like a relatively short version of .localhost.

Also there may be a risk with '.local', afaik that's more for multicast DNS, it's different than localhost, which will always be this machine. If the module 'namespacing' system wants to use DNS concepts, it needs to use them the same way, or it could get confusing.