Session suspension and restoration protocol

[Simon McVittie]

This document might be useful for the D-Bus side:
https://dbus.freedesktop.org/doc/dbus-api-design.html

On Mon, 18 Jun 2018 at 17:05:25 +0200, Roman Gilg wrote:
>         In certain high levels the compositor will ask the client through a
>         special D-Bus interface to restore its internal state. This interface
>         must be made available by the client on the address specified by the
>         desktop_id argument.

A D-Bus "address" isn't what you think it is. I think you mean a
*well-known bus name*, for example "org.gnome.Builder".

Note that GNOME Builder's desktop ID is "org.gnome.Builder.desktop"
but its D-Bus well-known name is "org.gnome.Builder", and any other
DBusActivatable application will follow the same pattern (it's part of
the Desktop Entry Specification). Be clear about which one you mean.

Strictly speaking, you should also specify that this is a name on the
*well-known session bus* (or "session bus" for short).

I would recommend having a canonical XML description (somewhere) for
the D-Bus side of this interface, similar to the one in the text of
https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus

>         The special interface name for the D-Bus call is
>         zxdg_session_suspension_v1

That isn't a valid D-Bus interface name. D-Bus interface names look
something like "com.example.SessionSuspension1". The equivalent of Wayland's
xdg_ is org.freedesktop. If you are proposing names in that namespace you
should mention them on the xdg at lists.freedesktop.org list, although I think
it'd be OK to say "please send feedback to the Wayland list".

To call a D-Bus method, you also need an object path. There are two
reasonable object paths for a singleton object related to the Desktop
Entry Specification's DBusActivatable protocol: either reuse the object
path corresponding to the desktop ID (for example /org/gnome/Builder),
or use an object path corresponding to your interface name
(for example /org/freedesktop/SessionSuspension1). If you use the
object path corresponding to the desktop ID, then it will be very
awkward to implement this protocol without involving the implementation
of DBusActivatable (for instance GApplication/GtkApplication in GNOME),
but the GApplication/GtkApplication or equivalent is probably the right
place to implement this protocol anyway, so either could work.

(The reason why object paths and interfaces are separate is that in a
more complex design, there might be many implementations of the same
interface in a process, for instance media players that provide one
object per file/track/stream at different object paths, each of them
implementing org.gnome.UPnP.MediaItem2. If interfaces are like abstract
base classes, then object paths are like pointers.)

Do you intend the D-Bus side of the protocol to be equally useful to
X11 apps, or is this a Wayland-only thing?

>         and the method being called by the
>         compositor on this interface is simply called 'restore'

D-Bus method names are conventionally in camel-case, so 'Restore'.

When we discussed this on #gnome-hackers we were talking about doing
restoration by passing the restored session ID as platform_data to the
Activate method defined by
https://standards.freedesktop.org/desktop-entry-spec/desktop-entry-spec-latest.html#dbus
which would mean that for trivial/stateless apps, it would be enough to
ignore it and just start up, which DBusActivatable implementations like
GtkApplication will already do. Is there a reason why you've opted to define
a new method instead?

>         compositor will issue on the next Wayland server launch the D-Bus
>         command:
> 
>         org.foo.bar /zxdg_session_suspension_v1 restore(1234)

D-Bus has no concept of a "command". The jargon term you're looking
for is a *method call*, which is one of several types of *message*.
If you want a pseudocode notation, you might want something like this:

    a D-Bus method call to a destination given by the desktop_id,
    with object path /org/freedesktop/SessionSuspension1, interface
    org.freedesktop.SessionSuspension1, method name Restore, and the
    client_id as a uint32 parameter, similar to the result of this
    dbus-send(1) command line:

    dbus-send --type=method_call --destination=org.gnome.Builder \
    /org/freedesktop/SessionSuspension1 \
    org.freedesktop.SessionSuspension1.Restore \
    uint32:1234

    (Of course, compositors or session managers should normally implement
    this in-process instead of by running dbus-send(1).)

>       <arg name="desktop_id" type="string" allow-null="true"
>            summary="desktop file id to restore the client via d-bus"/>

Does this include .desktop or not? GNOME Builder's desktop ID is
"org.gnome.Builder.desktop" but its D-Bus well-known name is
"org.gnome.Builder", and any other DBusActivatable application will
follow the same pattern (it's part of the Desktop Entry Specification).

>       The quit state ends when the compositor sends the D-Bus signal to
>       restart the client.

D-Bus method call, please. A D-Bus signal is a different jargon term
(they're two different types of message, and a method call is the one you
want when activating a service, because it has error-handling).