An idea for a newbie project: Wayland protocol dumper

[Pekka Paalanen]

Hi,

here is an idea for something that could be an advanced entry-level
project for getting to know the guts of the Wayland wire protocol, and
a self-contained newbie(?) project.

We have the environment variable WAYLAND_DEBUG, which you can use to
print out the protocol dump. It is useful, but it has come catches:

- The printing happens when the protocol wrapper function is called
  (sending), or a message is dispatched (receiving). This is not when
  the message is actually transmitted through the socket.

- The timestamp is also recorded during the printing, not when the
  message passes through the socket.

- If a protocol object does not have a listener set, dispatching of
  incoming messages is skipped, and nothing is printed even if there
  was a message.

- If a client uses multiple queues (wl_display has its own queue, so
  that happens always now), the message ordering is not preserved in
  the dump. The dump shows the order of dispatching, not the order on
  the wire.

The first two items are actually useful features sometimes, and
unwanted at other times. The last item causes confusion, because you
can see wl_display.delete_id for an object, then followed by an event
through that just-died object.

Also, when using WAYLAND_DEBUG=server, it is near-impossible to tell
the difference between clients.

To complement WAYLAND_DEBUG, it would be nice to have a proxy program
that would do the dumping. A tool, that would be used like

$ wayland-trace [options] client_program [program arguments]

This tool would connect to the Wayland server, and pass another socket
fd via WAYLAND_SOCKET to the client it forks. Then, the tool would act
as a proxy, collecting all the traffic.

Some open problems I cannot answer off-hand are:

- Some messages carry file descriptors. Is it possible to write a proxy
  without having the protocol definition (XML files) needed to decode
  the messages? If not, the dumper won't work for unknown protocol
  extensions.

- Should wayland-trace itself use libwayland-client and
  libwayland-server? Maybe not?

Some features that I think might be cool:

- Dumps optionally(?) in machine-readable format. (So people can write a
  GUI for inspecting dumps.)

- The ability to load .xml protocol specification files directly,
  without having to compile them into the program with e.g.
  wayland-scanner.

The major point of this tool would be to dump exactly what and when
goes over the wire.

What do you think, would it be useful?


Thanks,
pq