Resolve service endpoint from a URI environment variable

[paulhowardarm]

Summary

Introduce a mechanism in the Rust client (which would also apply uniformly to all clients) whereby a well-known and documented environment variable can be used for discovery of the correct Parsec service endpoint.

Rationale

Currently, the rust client is defaulting two things in the code:

• The nature of the IPC handler (currently defaulting to Unix socket, chiefly because that's the only form of IPC that Parsec supports today).
• The address of the endpoint (namely the socket path for Unix socket).

These things can be overridden if the caller passes in alternatives. However:

• If the caller is the SE driver (C client), then there is no means of passing through this information. This means the C client would break if the socket endpoint were configured to be anything other than the hard-coded default.
• Even when the caller has the ability to pass in the information, where should they get it from? Who has enough intelligence about the overall deployment to know what the service endpoint should be? Application developers won't typically have this intelligence - they will simply want to "use Parsec".

An environment variable would be an idiomatic way to allow configuration to be decided in the external environment, rather than in the client code. It would also allow different client processes to be directed at different service endpoints if Parsec evolves to support multiple endpoints, which it may do. This could be done with identical code on the client side.

Requirements

• Define and document an environment variable such as PARSEC_SERVICE_ENDPOINT.
• The variable should be defined as a URI (RFC 3986) so that it can specify a scheme as well as an endpoint address, such as unix:///tmp/parsec/parsec.sock.
• The rust client should obtain the value of this environment variable, but fall back on unix:///tmp/parsec/parsec.sock where it is undefined.
• The rust client should use both the scheme and the address segments of the URI to create a correct IPC handler pointed at the correct service endpoint. It remains the case that unix: would be the only supported scheme initially.
• Use of the environment variable should be default behaviour, although it should still be possible for callers to pass in explicit values to override this.
• Update the Parsec book to describe this behaviour of clients. It will need to become a general rule for client library development, since the same discovery logic will need to be replicated in the Go client and all other clients.

Discussion

In addition to endpoint discovery, it might also make sense for the authentication scheme to be set by an environment variable as well. But if we want to do that, then that's probably a separate request.

We'd need to think about how this impacts the threat model and its mitigations within the code, such as the permission check on the socket path. Presumably this permission check could still occur, because the check is performed on whatever socket path is configured. It's only the preferred source of the data that is changing.

[hug-dev]

Putting here as a reference that this can also be done in the parsec-tool less controversially

[ionut-arm]

Work for the initial design proposal has been done in #73, with one change: the unix scheme does not support an authority value and thus the correct value for encoding an address is unix:/path/to/socket

[hug-dev]

I think this was inspired from SPIFFE, so I raised this related issue.