Improved Application Lifecycle Events

The existing gadget lifecycle events stuff in the core-gadget spec can be greatly improved. It's currently fairly underspecified... here's how we can fix it...

Application Lifecycle Events

The Application Lifecycle Event capability allows an OpenSocial server and container to send notifications to a remote endpoint of the application developer's choosing whenever events significant to the lifecycle of an individual instance of the application occur. Such notifications can be used for a variety of purposes, including, but not limited to, the provisioning of additional resources external to the container that instances of the application require to operate.

Every instance of an application processed and rendered by a container follows the same basic general lifecycle.

The syntax used to identify individual types of events within the application lifecycle is:

  
  segment = 1*( ALPHA / DIGIT )
  prefix = segment *("." segment ) "."
  name = segment *("." segment)
  event = [prefix] "event" [ "." name ]

The following events are defined:

A developer can indicate interest in receiving notification whenever any of these lifecycle events occur by using the <Link> element with a "rel" attribute value equal to the identifier of the event. Containers are not, however, required to send lifecycle event notifications and MAY ignore any <Link> element specifying an event identifier.

The special identifier "org.opensocial.event" can be used to indicate interest in receiving notification for all event types.

Use of the "org.opensocial." prefix is reserved by this specification. Implementations MUST NOT use event identifiers that use the "org.opensocial." prefix other than those defined above. Implementations are free to define additional event type identifiers that use prefixes other than "org.opensocial.".

  
  <Module>
    <ModulePrefs>
      ...
      <Link rel="org.opensocial.event" href="http://example.org/event" />
      <Link rel="org.opensocial.event.registered" href="http://example.org/event/registered" />
      <Link rel="org.opensocial.event.unregistered" href="http://example.org/event/unregistered" />
      ...
    </ModulePrefs>
    <Content type="html">
      ...
    </Content>
  </Module>

Lifecycle Event Notifications

Whenever a significant lifecycle event occurs for a particular application, the container MAY send an event notification to the IRI identified by any <Link> element provided whose "rel" attribute values identify the event. If the container supports sending event notifications, one notification SHOULD be sent for each matching <Link> element.

For instance, given the following partial specification:

  <Module>
    <ModulePrefs>
      ...
      <Link rel="org.opensocial.event" href="http://example.org/event" />
      <Link rel="org.opensocial.event.registered" href="http://example.org/event/registered" />
      <Link rel="org.opensocial.event.unregistered" href="http://example.org/event/unregistered" />
      ...
    </ModulePrefs>
    <Content type="html">
      ...
    </Content>
  </Module>

When the application is registered with the container, two event notifications will be sent:

• One to the endpoint "http://example.org/event" identified by the "org.opensocial.event" rel value, and
• One to the endpoint "http://example.org/event/registered" identified by the "org.opensocial.event.registered" rel value.

Each event notification is sent as an HTTP POST message containing an Activity object as defined by the JSON Activity Streams specification.

• The "actor" identifies the entity that triggered the event. Examples can be individual users (e.g. the user who registered the application) or the container.
• The "verb" identifies the event that triggered the notification. The value MUST be the identifier of the event that triggered the notification.
• The "object" provides specific information about the application for which the event occurred.
• For certain events, the "target" specifies information about the entity to which the action triggering the event occurred.

For example, a notification indicating that a new application was registered with a container would look like the following:

  POST /event HTTP/1.1
  Host: example.org
  Content-Type: application/stream+json
  
  {
    "actor": {
      "objectType":"person",
      "displayName":"Joe",
      "id":"acct:joe@example.net"
    },
    "verb":"org.opensocial.event.register",
    "object": {
      "objectType":"opensocial-application",
      "displayName":"My Application",
      "url":"http://example.com/opensocial/applications/1"
    },
    "target": {
      "objectType":"service",
      "displayName":"My OpenSocial Container",
      "url":"http://example.com/opensocial"
    }
  }

A notification indicating that an existing application has been installed within a particular page would look like:

  POST /event HTTP/1.1
  Host: example.org
  Content-Type: application/stream+json
  
  {
    "actor": {
      "objectType":"person",
      "displayName":"Joe",
      "id":"acct:joe@example.net"
    },
    "verb":"org.opensocial.event.install",
    "object": {
      "objectType":"opensocial-application",
      "displayName":"My Application",
      "url":"http://example.com/opensocial/applications/1"
    },
    "target": {
      "objectType":"project",
      "displayName":"My Project",
      "url":"http://example.com/opensocial/project/1"
    }
  }

A notification indicating that the container has restricted the functionality of a particular application instance could look something like:

  POST /event HTTP/1.1
  Host: example.org
  Content-Type: application/stream+json
  
  {
    "actor": {
      "objectType":"service",
      "displayName":"My OpenSocial Container",
      "url":"http://example.com/opensocial"
    },
    "verb":"org.opensocial.event.restriction",
    "object": {
      "objectType":"opensocial-application",
      "displayName":"My Application",
      "url":"http://example.com/opensocial/applications/1",
      "rate-limit": 10
    }
  }

A hypothetical "rate-limit" property is used to provide an example of how specific individual properties relating to the application instance can be communicated within the event notification.

If the <Link> element includes an "authz" attribute that specifies a value other than "none", the notification MUST be authenticated using the authentication mechanism specified as described in <xref target="authentication"/>. If the "authz" attribute specifies a value of "none", no authentication mechanism is to be used. If the "authz" attribute is not specified, the notification MUST be authenticated using the Signed Fetch mechanism.

Responses to event notification requests are considered to be insignificant by this specification.