[RFC] Event prefixing policy

Tue Feb 12 16:59:51 UTC 2013

Hi Steve,

On 12/02/13 06:48, Steve Langasek wrote:
> Hi James,
> 
> On Thu, Jan 31, 2013 at 08:25:08PM +0000, James Hunt wrote:
> 
>> For Enhanced User Sessions in Upstart, we originally planned for session
>> jobs being supervised by a Session Init (upstart running as a non-priv
>> user) to react to *both* system events and session events when the 'start
>> on' stanza is specified in the usual form:
> 
>>   start on foo
> 
>> However, we now feel that this is likely to be a cause of some confusion since
>> if there were jobs at both the system (pid 1) level *and* the user level that
>> reacted to that event, the 'foo' event would cause both of them to start. This
>> may or may not be desirable :) ...
> 
>> /etc/init/bar.conf:
>>    start on foo
> 
>> $HOME/.config/upstart/bar.conf:
>>    start on foo
> 
>> $ sudo initctl emit foo   # OUTCOME: *both* bar jobs start.
>> $ initctl emit foo        # OUTCOME: only user job starts
> 
>> To avoid confusion, there are 2 approaches we're looking at (if you can
>> think of others, please speak up):
> 
> I think those are the main two approaches to consider.
> 
>> (1) Require session jobs to specify the ':sys:' prefix to react to system
>> events (no prefix or ':user:' would therefore match user events).
> 
>>   start on :sys:foo  # start if 'foo' event emitted at PID 1 level.
>>   start on foo       # start if 'foo' event emitted at Session Init level.
>>   start on :user:foo # start if 'foo' event emitted at Session Init level.
> 
>> (2) Require session jobs to specify the ':user:' prefix to react to user events
>> (no prefix or ':sys:' would therefore match system events).
> 
>>   start on :user:foo # start if 'foo' event emitted at Session Init level.
>>   start on foo       # start if 'foo' event emitted at PID 1 level.
>>   start on :sys:foo  # start if 'foo' event emitted at PID 1 level.
> 
> I would argue against allowing two different syntaxes for the same thing. 
> If 'start on foo' is unambiguous, it should also be the only way to write it
> - whichever of :sys: and :user: is not required for disambiguation should be
> prohibited altogether.
> 
>> Option (1) has the virtue of being explicit so there is no doubt about
>> what is being requested.  This probably wins wrt the Principle of Least
>> Astonishment, but may be unwieldy if users have more jobs reacting to
>> system events that session events (*).
> 
>> Option (2) has the virtue that it would allow users to develop a job, test
>> it via a Session Init and then deploy as a system job with no syntax
>> change.  Since we imagine session jobs may wish to react to udev messages,
>> this would simplify the jobs and make them compatible with system-level
>> jobs.  Compare:
> 
>>   start on      net-device-added INTERFACE=eth0
>>   start on :sys:net-device-added INTERFACE=eth0
> 
> Option 2 is certainly my preference in terms of semantics, though it may
> make the implementation hairier than we might like (since the session init
> then has to treat the bridged events specially, by *not* adding a prefix to
> their names).
> 
>> If a user _really_ wants a job to react to both system- and user-level
>> events, we could change the meaning of the '::' prefix to mean 'match all
>> prefixes'.  This is probably clearer than making the 'no prefix' mean
>> 'match all prefixes' since the extra syntactical sugar gives some
>> indication that this isn't a normal event match.
> 
> I don't think 'match all prefixes' is really useful for user jobs; a job
> author should really know already where the event is going to come from.
> The only way I see this being /potentially/ useful is to improve portability
> of jobs between user and system init, /if/ system init supported the same
> syntax - but I don't think that's really a good idea either.  Again, I think
> it's better to not allow more than one way to specify the same event as this
> is likely to just cause confusion.
> 
> In lp:~jamesodhunt/upstart/event-prefixes, I see that you've opted for
> option 1) above.  Maybe you could elaborate on why you preferred this
> approach?
My current branch does indeed favour option 1 since:

- it's less surprising I think that no prefix means 'my current namespace'.
- the ':sys:' prefix is explicit and even if you haven't read the man pages
hints that its referencing something out of the ordinary (outside the current
namespace).

To some extent, I think we should consider the relative proportion of user jobs
that we envisage would need to reference system events. As a data point,
Stéphanes branch of planned default user jobs currently doesn't (need to) make
any mention of system events but certainly makes use of user events.

The standard user jobs can of course use whichever syntax we decide so maybe we
need to understand the sorts of jobs users themselves will want to write that
would make use of system-level events. I wonder if most of these will in fact
relate to bridged udev events?

---

As an alternative approach, we could introduce a 'match' stanza that would
ensure that, if specified, non-prefixed events would actually match those events
whose prefix is specified by the match stanza. For example, the following 2 user
jobs would be equivalent:

job1.conf:
  # reference 2 system-level events explicitly
  start on :sys:foo and :sys:started bar

job2.conf:
  # reference 2 system-level events implicitly
  match :sys:
  start on foo and started bar

Pros and Cons of adding a 'match' stanza:

+ means start/stop on conditions can be identical to system-level
+ less visual 'noise' in complex conditions
+ user jobs can be promoted to system jobs without change (since 'match :sys:'
would be the default at the system level anyway) [1]

- introducing a new stanza has an impact on stateful re-exec (new support code
and tests required).

Kind regards,

James.

[1] - Note that for minimal 'noise', the match stanza could even live in an
override file.
--
James Hunt
____________________________________
http://upstart.ubuntu.com/cookbook
http://upstart.ubuntu.com/cookbook/upstart_cookbook.pdf