A locator plugin should return the YAML contents, not HTTPS URL

[AkihiroSuda]

On the second thought, a locator plugin should return the YAML contents, not HTTPS URL, so as to support non-HTTP and non-local remotes

Originally posted by @AkihiroSuda in #3937 (comment)

[jandubois]

This is slightly problematic because then most locator plugins must implement network transport, or expect curl or wget to be available.

I would suggest that a plugin can return either a URL/filename, or the YAML content:

If the output matches /^{/ or /^\S+:\s/, or includes a newline, it is treated as YAML.

Otherwise it is interpreted as a URL (or local filename).

This mechanism can be implemented later, as it is fully backwards compatible. So we can just ship the URL mechanism in 2.0, if we run out of time.

[AkihiroSuda]

This is slightly problematic because then most locator plugins must implement network transport, or expect curl or wget to be available.

Not necessary. A plugin can just return a content like:

base:
- https://...

[jandubois]

Not necessary. A plugin can just return a content like:

No, that does not work for provisioning scripts and probes:

provision:
- mode: system
  file: github:ORG/REPO/script.sh

[jandubois]

The other issue we have to resolve is how to determine the instance name when the template is provided as YAML? We would have to require that the user specifies --name, the same way we do it when we read the template from STDIN via -.

Maybe it is a stupid idea (I need to sleep), but we could print the name to STDERR when STDOUT is YAML and not a URL?

Maybe require STDERR to be in JSON in this case, so it is extensible if later we want to return even more metadata?

[jandubois]

If the output matches /^{/ or /^\S+:\s/, or includes a newline, it is treated as YAML.

Otherwise it is interpreted as a URL (or local filename).

The same logic is used in #4134 to determine if a file contains YAML or a symlink (LooksLikeSymlink in pkg/limatmpl/github.go).

[AkihiroSuda]

Stderr is for errors.
Why not just print structured data in stdout?

[jandubois]

Stderr is for errors.

That is just a convention. Even limactl is using it also for logging and not just for errors.

It is just a second file descriptor, so we can capture a separate output stream.

The plugins are not supposed to be invoked directly by the user, but only indirectly via limactl. There is just a single location calling them (specific to url-* plugins, not all plugins):

lima/pkg/limatmpl/locator.go

Line 333 in ccc3adf

stdout, err := cmd.Output()

So we could just define the API for url plugins as:

If the exit code is 0, then STDERR can provide additional data via JSON.
If the exit code is non-0, then STDERR may have an error message that should be reported to the user.

We probably should REQUIRE that STDERR returns JSON with a name property (even if it is empty), to signify that STDOUT is the actual content and not a redirected URL. Because the heuristics to determine if the output is YAML don't apply to shell scripts, or potentially random data, in the future.

Why not just print structured data in stdout?

Because it is difficult to construct in a shell script. How can you create a document containing both the file content, plus additional properties when you have the YAML just as a text string?

We could provide a 4th open file to the plugin and write to &3, but I think this is not needed, and makes manual testing of the plugin more complicated than it needs to be. I think using the special rules I gave above is totally fine.

if [[ SOME_ERROR ]]; then
    echo "This is wrong" >&2
    exit 1
fi
printf '{"name": "%s"}' "$NAME" >&2
echo "$CONTENT"

And it is completely backwards compatible with what we have right now.

[jandubois]

I just realized another challenge: the template embedding code needs to know how to locate relative template or file references from the YAML (if the locator was for a template and not a script).

So in addition to the name we will also need a rootURL that can be combined with a relative path name to create a full URL to a different file.

If the plugin can return a rootURL with a custom scheme, then we need to make some assumptions because the URL is opaque and the combining semantics in general are undefined.

We already assume path semantics for our URLs, so it is not unreasonable to expect the rootURL to be a string that can just be joined (without further separator) with a relative path.

It would return something like custom: for a root URL of the custom namespace, or custom:path/ for the location where the current object was found.

If the template has base: common, then the templating code could use strings.Join(rootURL, "common") to get custom:path/common and pass this again to the plugin to retrieve the relative base template.

[jandubois]

@AkihiroSuda I would like to remove this issue from the 2.0 milestone.

As I've shown above, there are more things to consider than just returning the file content, and I think we should think this through carefully instead of squeezing this into the 2.0 release, and then having to change it in an incompatible way afterwards. I'm not aware of any pending usage that needs this functionality right now.

I think for 2.0 we should rather concentrate on comprehensive integration tests and documentation of the custom locator functionality that is already implemented, and then extend this after the release.

[AkihiroSuda]

Maybe a plugin should just fetch a non-http content into ~/Library/Caches/lima/download/by-url-sha256/..., and return a local path to there.

Using the cache dir is optional, but recommended to support limactl prune

[jandubois]

Maybe a plugin should just fetch a non-http content into ~/Library/Caches/lima/download/by-url-sha256/..., and return a local path to there.

This will still not work: if you fetch a template, then only the template is downloaded into the cache. If it references a relative base template or script, these will become cache references to files that have not yet been downloaded, so fetching the content will fail. But even if they had been downloaded already, the path semantics would be broken by storing each file under a digest directory name, so they wouldn't be found anyways.

I still think this is solvable with extra work, but don't want to spend any time thinking about it right now.

Just for later reference, these use-cases (including relative references) should be enabled if the feature is implemented properly:

• fetch data from a sqlite3 database
• fetch data from Kubernetes ConfigMaps
• fetch data embedded in a Go binary