Re: [Spice-devel] [PATCH spice-common 3/3] docs: add spice URI scheme
On Tue, Jan 15, 2019 at 06:00:09PM +0400, Marc-André Lureau wrote:
> Hi
>
> On Tue, Jan 15, 2019 at 4:53 PM Christophe Fergeau
> wrote:
> >
> > Hey,
> >
> > On Fri, Jan 11, 2019 at 11:07:14PM +0400, marcandre.lur...@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
> > > +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 , , ,
> > > +, and 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 portion of a Spice
> > > +URI, the 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¶m2=value2...
> >
> > I'd mention 'userinfo' in that URI.
>
> The point of this is to show a general form, not a form that has all
> the details.
>
> Given that it is discouraged to use userinfo (unless it is done
> carefully), I don't think we need to mention it here.
>
> However, there could be more details about it, a line such as:
>
> userinfo =
Ok.
>
>
> >
> > > +The 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¶m2=value2...
> > URI-unix = spice+unix://path-absolute
> >
> > Or decide that for now, the current definition is good enough ;)
>
> I agree it could be improved, but for a v1, I would rather have
> external contributions for this kind of refinements :)
Ok.
Christophe
signature.asc
Description: PGP signature
___
Spice-devel mailing list
Spice-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/spice-devel
Re: [Spice-devel] [PATCH spice-common 3/3] docs: add spice URI scheme
Hi
On Tue, Jan 15, 2019 at 4:53 PM Christophe Fergeau wrote:
>
> Hey,
>
> On Fri, Jan 11, 2019 at 11:07:14PM +0400, marcandre.lur...@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
> > +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 , , ,
> > +, and 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 portion of a Spice
> > +URI, the 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¶m2=value2...
>
> I'd mention 'userinfo' in that URI.
The point of this is to show a general form, not a form that has all
the details.
Given that it is discouraged to use userinfo (unless it is done
carefully), I don't think we need to mention it here.
However, there could be more details about it, a line such as:
userinfo =
You can also read usage is discouraged there.
>
> > +The 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¶m2=value2...
> URI-unix = spice+unix://path-absolute
>
> Or decide that for now, the current definition is good enough ;)
I agree it could be improved, but for a v1, I would rather have
external contributions for this kind of refinements :)
Thanks
>
>
> Christophe
> ___
> Spice-devel mailing list
> Spice-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/spice-devel
--
Marc-André Lureau
___
Spice-devel mailing list
Spice-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/spice-devel
Re: [Spice-devel] [PATCH spice-common 3/3] docs: add spice URI scheme
Hey,
On Fri, Jan 11, 2019 at 11:07:14PM +0400, marcandre.lur...@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
> +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 , , ,
> +, and 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 portion of a Spice
> +URI, the 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¶m2=value2...
I'd mention 'userinfo' in that URI.
> +The 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¶m2=value2...
URI-unix = spice+unix://path-absolute
Or decide that for now, the current definition is good enough ;)
Christophe
signature.asc
Description: PGP signature
___
Spice-devel mailing list
Spice-devel@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/spice-devel
Re: [Spice-devel] [PATCH spice-common 3/3] docs: add spice URI scheme
> > On Mon, Jan 14, 2019 at 8:36 PM Frediano Ziglio wrote: > > > > > > > > From: Marc-André Lureau > > > > > > Signed-off-by: Marc-André Lureau > > > --- > > > docs/Makefile.am | 1 + > > > docs/meson.build | 2 +- > > > docs/spice_uri_scheme.txt | 131 ++ > > > 3 files changed, 133 insertions(+), 1 deletion(-) > > > create mode 100644 docs/spice_uri_scheme.txt > > > > > > diff --git a/docs/Makefile.am b/docs/Makefile.am > > > index e7e126b..6f7a0ac 100644 > > > --- a/docs/Makefile.am > > > +++ b/docs/Makefile.am > > > @@ -3,6 +3,7 @@ CLEANFILES = > > > > > > > > > > +documentation. > > > + > > > +Data Types > > > +-- > > > + > > > +Spice URIs can be percent-encoded as specified in [RFC3986] and MUST > > > +be decoded. After decoding, the following type constraints and > > > +semantics apply: > > > + > > > +string > > > +~~ > > > + > > > +Values of "string" type are UTF-encoded strings as specified in > > > > Minor: UTF8, not any UTF. > > ack series with that change? > I didn't read all this document, I saw Christophe did it, I just caught this minor typo by "accident". > > > > > +[RFC3629]. > > > + > > > +ushort > > > +~~ > > > + > > > +The "ushort" values represent unsigned 16-bit integers expressed > > > +in decimal digits with value between 0-65535 inclusive. > > Frediano ___ Spice-devel mailing list Spice-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/spice-devel
Re: [Spice-devel] [PATCH spice-common 3/3] docs: add spice URI scheme
On Mon, Jan 14, 2019 at 8:36 PM Frediano Ziglio wrote: > > > > > From: Marc-André Lureau > > > > Signed-off-by: Marc-André Lureau > > --- > > docs/Makefile.am | 1 + > > docs/meson.build | 2 +- > > docs/spice_uri_scheme.txt | 131 ++ > > 3 files changed, 133 insertions(+), 1 deletion(-) > > create mode 100644 docs/spice_uri_scheme.txt > > > > diff --git a/docs/Makefile.am b/docs/Makefile.am > > index e7e126b..6f7a0ac 100644 > > --- a/docs/Makefile.am > > +++ b/docs/Makefile.am > > @@ -3,6 +3,7 @@ CLEANFILES = > > > > > > +documentation. > > + > > +Data Types > > +-- > > + > > +Spice URIs can be percent-encoded as specified in [RFC3986] and MUST > > +be decoded. After decoding, the following type constraints and > > +semantics apply: > > + > > +string > > +~~ > > + > > +Values of "string" type are UTF-encoded strings as specified in > > Minor: UTF8, not any UTF. ack series with that change? > > > +[RFC3629]. > > + > > +ushort > > +~~ > > + > > +The "ushort" values represent unsigned 16-bit integers expressed > > +in decimal digits with value between 0-65535 inclusive. > > Frediano > ___ > Spice-devel mailing list > Spice-devel@lists.freedesktop.org > https://lists.freedesktop.org/mailman/listinfo/spice-devel -- Marc-André Lureau ___ Spice-devel mailing list Spice-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/spice-devel
Re: [Spice-devel] [PATCH spice-common 3/3] docs: add spice URI scheme
> > From: Marc-André Lureau > > Signed-off-by: Marc-André Lureau > --- > docs/Makefile.am | 1 + > docs/meson.build | 2 +- > docs/spice_uri_scheme.txt | 131 ++ > 3 files changed, 133 insertions(+), 1 deletion(-) > create mode 100644 docs/spice_uri_scheme.txt > > diff --git a/docs/Makefile.am b/docs/Makefile.am > index e7e126b..6f7a0ac 100644 > --- a/docs/Makefile.am > +++ b/docs/Makefile.am > @@ -3,6 +3,7 @@ CLEANFILES = > > +documentation. > + > +Data Types > +-- > + > +Spice URIs can be percent-encoded as specified in [RFC3986] and MUST > +be decoded. After decoding, the following type constraints and > +semantics apply: > + > +string > +~~ > + > +Values of "string" type are UTF-encoded strings as specified in Minor: UTF8, not any UTF. > +[RFC3629]. > + > +ushort > +~~ > + > +The "ushort" values represent unsigned 16-bit integers expressed > +in decimal digits with value between 0-65535 inclusive. Frediano ___ Spice-devel mailing list Spice-devel@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/spice-devel
[Spice-devel] [PATCH spice-common 3/3] docs: add spice URI scheme
From: Marc-André Lureau
Signed-off-by: Marc-André Lureau
---
docs/Makefile.am | 1 +
docs/meson.build | 2 +-
docs/spice_uri_scheme.txt | 131 ++
3 files changed, 133 insertions(+), 1 deletion(-)
create mode 100644 docs/spice_uri_scheme.txt
diff --git a/docs/Makefile.am b/docs/Makefile.am
index e7e126b..6f7a0ac 100644
--- a/docs/Makefile.am
+++ b/docs/Makefile.am
@@ -3,6 +3,7 @@ CLEANFILES =
ASCIIDOC_FILES = \
spice_protocol.txt \
+ spice_uri_scheme.txt\
$(NULL)
ASCIIDOC_FLAGS = -n -a icons -a toc
diff --git a/docs/meson.build b/docs/meson.build
index 8901762..51a10c3 100644
--- a/docs/meson.build
+++ b/docs/meson.build
@@ -1,7 +1,7 @@
if get_option('manual')
asciidoc = find_program('asciidoc', required : false)
if asciidoc.found()
-foreach f: ['spice_protocol.txt']
+foreach f: ['spice_protocol.txt', 'spice_uri_scheme.txt']
custom_target('HTML for @0@'.format(f),
input : f,
output : '@BASENAME@.html',
diff --git a/docs/spice_uri_scheme.txt b/docs/spice_uri_scheme.txt
new file mode 100644
index 000..0e4bcf9
--- /dev/null
+++ b/docs/spice_uri_scheme.txt
@@ -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
+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 , , ,
+, and 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 portion of a Spice
+URI, the 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¶m2=value2...
+
+The host information and each parameter value specify information
+used in establishing or operating the remote desktop session as
+specified in Section "URI Parameters".
+
+URI Parameters
+--
+
+A description of host information and URI parameters is provided in
+this section. Information on the constraints of various data types is
+provided in Section "Data Types". All parameters are considered optional;
+however, a client will not be able to connect without sufficient
+information.
+
+A parameter without a specified default value indicates that no
+default value is implied by this URI scheme; however, Spice clients
+can apply implementation-dependent default behaviors otherwise
+consistent with this document.
+
+The and values in the "spice://" and "spice+tls://" URIs
+specify the address of the Spice server on the remote host:
+
+[options="header"]
+|===
+| Name | Type | Description | Default
+| host | string | Spice server hostname or IP | none
+| port | ushort | Spice server port | none
+|===
+
+The 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
+|===
+
+The Spice URI parameter values specify remote desktop connection or
+session properties, including aspects of client operation, usability,
+and security as specified in the table below:
+
+[options="header"]
+|===
+| Name | Type | Description | Default
+| port | ushort | Spice server port (legacy) | none
+| tls-port | ushort | Spice server TLS port (legacy) | none
+| password | string | Spice server password (legacy) | none
+| ...|| |
+|
