[Spice-devel] [PATCH spice-common 3/3] docs: add spice URI scheme

[Christophe Fergeau]

Hey,

On Fri, Jan 11, 2019 at 11:07:14PM +0400, marcandre.lureau at redhat.com wrote:
> @@ -0,0 +1,131 @@
> +The "spice" URI scheme
> +======================
> +
> +This document is inspired by 'The "vnc" URI Scheme' (rfc7869) and
> +attempts to document a standard Spice URI scheme.
> +
> +The normative syntax of the Spice URI is defined in the <spice-uri>
> +rule in the following syntax specification.  This specification
> +uses the Augmented Backus-Naur Form (ABNF) as described in
> +[RFC5234].  The Spice URI conforms to the generic URI syntax
> +specified in [RFC3986].  The <userinfo>, <host>, <port>,
> +<unreserved>, and <pct-encoded> rules are defined in [RFC3986].
> +
> + spice-uri = spice-scheme "://" [ userinfo "@" ] [ host [ ":" port ] ]
> +              [ "?" [ spice-params ] ]
> +
> + spice-scheme = "spice" / "spice+unix" / "spice+tls"
> +
> + spice-params = param "=" value *("&" param "=" value) ["&"]
> +
> + param = 1*( param-char )
> +
> + value = *( param-char )
> +
> + param-char = unreserved / pct-encoded / unreserved-symbols
> +
> + unreserved-symbols = ":" / "/" / "@" / "!" / "$" / "'"
> +                       / "(" / ")" / "*" / "," / ";"
> +
> +The "?", "=", and "&" characters are used to delimit Spice parameters
> +and must be percent-encoded when representing a data octet as
> +specified in [RFC3986].  Within the <spice-params> portion of a Spice
> +URI, the <unreserved-symbols> do not have special meaning and need not
> +be percent-encoded when representing a data octet.
> +
> +A Spice URI has the general form:
> +
> + spice-scheme://host:port?param1=value1&param2=value2...

I'd mention 'userinfo' in that URI.

> +The <host> value in the "spice+unix://" URI specify the UNIX domain
> +socket path of the Spice server on the local host:
> +
> +[options="header"]
> +|=======================================================================
> +| Name       | Type       | Description                     | Default
> +| host       | string     | UNIX domain socket path         | none
> +|=======================================================================

RFC3986 has a definition for a 'path-absolute', but this is something which is
concatenated to the 'host'. A 'host' for RFC3986 cannot contain a '/':

   host          = IP-literal / IPv4address / reg-name
with
   reg-name      = *( unreserved / pct-encoded / sub-delims )
   unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
   sub-delims    = "!" / "$" / "&" / "'" / "(" / ")"
                   / "*" / "+" / "," / ";" / "="

I guess you could rework the current definition with something like:

URI = URI-unix / URI-net
URI-net = spice-scheme-net://host:port?param1=value1&param2=value2...
URI-unix = spice+unix://path-absolute

Or decide that for now, the current definition is good enough ;)


Christophe
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 833 bytes
Desc: not available
URL: <https://lists.freedesktop.org/archives/spice-devel/attachments/20190115/89e71bfe/attachment.sig>