Merge lp:~chipaca/ubuntu-push/the-push-automatic into lp:ubuntu-push

[John Lenton]

gsettings!

=== added directory 'click/cblacklist'
=== added file 'click/cblacklist/cblacklist.go'
--- click/cblacklist/cblacklist.go	1970-01-01 00:00:00 +0000
+++ click/cblacklist/cblacklist.go	2014-08-04 15:37:24 +0000
@@ -0,0 +1,75 @@
+/*
+ Copyright 2013-2014 Canonical Ltd.
+
+ This program is free software: you can redistribute it and/or modify it
+ under the terms of the GNU General Public License version 3, as published
+ by the Free Software Foundation.
+
+ This program is distributed in the hope that it will be useful, but
+ WITHOUT ANY WARRANTY; without even the implied warranties of
+ MERCHANTABILITY, SATISFACTORY QUALITY, or FITNESS FOR A PARTICULAR
+ PURPOSE.  See the GNU General Public License for more details.
+
+ You should have received a copy of the GNU General Public License along
+ with this program.  If not, see <http://www.gnu.org/licenses/>.
+*/
+
+// Package cblacklist accesses the g_settings notification blacklist
+
+package cblacklist
+
+/*
+#cgo pkg-config: gio-unix-2.0
+#cgo pkg-config: glib-2.0
+
+#include <stdlib.h>
+#include <gio/gio.h>
+
+#define BLACKLIST_CONFIG_SCHEMA_ID "com.ubuntu.notifications.hub"
+#define BLACKLIST_KEY "blacklist"
+
+int is_blacklisted(const char *pkgname, const char *appname) {
+    static GSettings *pushSettings = NULL;
+    GVariantIter *iter;
+    gchar *pkg;
+    gchar *app;
+    int blacklisted = 0;
+
+    if (!pushSettings) {
+        GSettingsSchemaSource * source = g_settings_schema_source_get_default ();
+        if (!g_settings_schema_source_lookup (g_settings_schema_source_get_default (), BLACKLIST_CONFIG_SCHEMA_ID, TRUE)) {
+            return -1;
+        }
+        pushSettings = g_settings_new(BLACKLIST_CONFIG_SCHEMA_ID);
+    }
+    GVariant *blacklist = g_settings_get_value(pushSettings, BLACKLIST_KEY);
+    g_variant_get (blacklist, "a(ss)", &iter);
+    while (g_variant_iter_loop (iter, "(ss)", &pkg, &app)) {
+        if (0==g_strcmp0(pkg, pkgname) && 0==g_strcmp0(app, appname)) {
+            blacklisted = 1;
+            break;
+        }
+        // No need to free pkg and app, according to GVariant array example
+    }
+    g_variant_iter_free (iter);
+    g_variant_unref (blacklist);
+    return blacklisted;
+}
+
+*/
+import "C"
+
+import (
+	"unsafe"
+
+	"launchpad.net/ubuntu-push/click"
+)
+
+// IsBlacklisted returns true if the application is in the gsettings blacklist
+func IsBlacklisted(app *click.AppId) bool {
+	pkgname := C.CString(app.Package)
+	appname := C.CString(app.Application)
+	defer C.free(unsafe.Pointer(pkgname))
+	defer C.free(unsafe.Pointer(appname))
+	return C.is_blacklisted(pkgname, appname) == 1
+}

=== modified file 'click/click.go'
--- click/click.go	2014-07-25 21:50:53 +0000
+++ click/click.go	2014-08-04 15:37:24 +0000
@@ -22,7 +22,6 @@
 	"encoding/json"
 	"errors"
 	"fmt"
-	"io/ioutil"
 	"path/filepath"
 	"regexp"
 	"strings"
@@ -43,9 +42,6 @@
 	original    string
 }
 
-var hookPath = filepath.Join(xdg.Data.Home(), "ubuntu-push-client", "helpers")
-var hookExt = ".json"
-
 // from https://wiki.ubuntu.com/AppStore/Interfaces/ApplicationId
 // except the version is made optional
 var rxClick = regexp.MustCompile(`^([a-z0-9][a-z0-9+.-]+)_([a-zA-Z0-9+.-]+)(?:_([0-9][a-zA-Z0-9.+:~-]*))?$`)
@@ -121,46 +117,6 @@
 	}
 }
 
-type hookFile struct {
-	AppId string `json:"app_id"`
-	Exec  string `json:"exec"`
-}
-
-// Helper figures out the app id and executable of the untrusted
-// helper for this app.
-func (app *AppId) Helper() (helperAppId string, helperExec string) {
-	if !app.Click {
-		return "", ""
-	}
-	// xxx: should probably have a cache of this
-	matches, err := filepath.Glob(filepath.Join(hookPath, app.Package+"_*"+hookExt))
-	if err != nil {
-		return "", ""
-	}
-	var v hookFile
-	for _, m := range matches {
-		abs, err := filepath.EvalSymlinks(m)
-		if err != nil {
-			continue
-		}
-		data, err := ioutil.ReadFile(abs)
-		if err != nil {
-			continue
-		}
-		err = json.Unmarshal(data, &v)
-		if err != nil {
-			continue
-		}
-		if v.Exec != "" && (v.AppId == "" || v.AppId == app.Base()) {
-			basename := filepath.Base(m)
-			helperAppId = basename[:len(basename)-len(hookExt)]
-			helperExec = filepath.Join(filepath.Dir(abs), v.Exec)
-			return helperAppId, helperExec
-		}
-	}
-	return "", ""
-}
-
 func (app *AppId) Versioned() string {
 	if app.Click {
 		if app.Version == "" {

=== modified file 'click/click_test.go'
--- click/click_test.go	2014-07-25 21:50:53 +0000
+++ click/click_test.go	2014-08-04 15:37:24 +0000
@@ -19,8 +19,6 @@
 import (
 	"encoding/json"
 	"fmt"
-	"os"
-	"path/filepath"
 	"testing"
 
 	. "launchpad.net/gocheck"
@@ -183,78 +181,4 @@
 	c.Assert(err, Equals, ErrMissingAppId)
 	c.Check(app, NotNil)
 	c.Check(app.Original(), Equals, "_non-existent-app")
-
-}
-
-type helperSuite struct {
-	oldHookPath string
-	symlinkPath string
-}
-
-var _ = Suite(&helperSuite{})
-
-func (s *helperSuite) SetUpTest(c *C) {
-	s.oldHookPath = hookPath
-	hookPath = c.MkDir()
-	s.symlinkPath = c.MkDir()
-}
-
-func (s *helperSuite) createHookfile(name string, content string) error {
-	symlink := filepath.Join(hookPath, name) + ".json"
-	filename := filepath.Join(s.symlinkPath, name)
-	f, err := os.Create(filename)
-	if err != nil {
-		return err
-	}
-	_, err = f.WriteString(content)
-	if err != nil {
-		return err
-	}
-	err = os.Symlink(filename, symlink)
-	if err != nil {
-		return err
-	}
-	return nil
-}
-
-func (s *helperSuite) TearDownTest(c *C) {
-	hookPath = s.oldHookPath
-}
-
-func (s *helperSuite) TestHelperBasic(c *C) {
-	c.Assert(s.createHookfile("com.example.test_test-helper_1", `{"exec": "tsthlpr"}`), IsNil)
-	app, err := ParseAppId("com.example.test_test-app_1")
-	c.Assert(err, IsNil)
-	hid, hex := app.Helper()
-	c.Check(hid, Equals, "com.example.test_test-helper_1")
-	c.Check(hex, Equals, filepath.Join(s.symlinkPath, "tsthlpr"))
-}
-
-func (s *helperSuite) TestHelperFindsSpecific(c *C) {
-	// Glob() sorts, so the first one will come first
-	c.Assert(s.createHookfile("com.example.test_aaaa-helper_1", `{"exec": "aaaaaaa", "app_id": "com.example.test_test-other-app"}`), IsNil)
-	c.Assert(s.createHookfile("com.example.test_test-helper_1", `{"exec": "tsthlpr", "app_id": "com.example.test_test-app"}`), IsNil)
-	app, err := ParseAppId("com.example.test_test-app_1")
-	c.Assert(err, IsNil)
-	hid, hex := app.Helper()
-	c.Check(hid, Equals, "com.example.test_test-helper_1")
-	c.Check(hex, Equals, filepath.Join(s.symlinkPath, "tsthlpr"))
-}
-
-func (s *helperSuite) TestHelperCanFail(c *C) {
-	c.Assert(s.createHookfile("com.example.test_aaaa-helper_1", `{"exec": "aaaaaaa", "app_id": "com.example.test_test-other-app"}`), IsNil)
-	app, err := ParseAppId("com.example.test_test-app_1")
-	c.Assert(err, IsNil)
-	hid, hex := app.Helper()
-	c.Check(hid, Equals, "")
-	c.Check(hex, Equals, "")
-}
-
-func (s *clickSuite) TestHelperlegacy(c *C) {
-	appname := "ubuntu-system-settings"
-	app, err := ParseAppId("_" + appname)
-	c.Assert(err, IsNil)
-	hid, hex := app.Helper()
-	c.Check(hid, Equals, "")
-	c.Check(hex, Equals, "")
 }

=== modified file 'client/service/postal.go'
--- client/service/postal.go	2014-07-29 15:38:04 +0000
+++ client/service/postal.go	2014-08-04 15:37:24 +0000
@@ -30,6 +30,7 @@
 	"launchpad.net/ubuntu-push/bus/urldispatcher"
 	"launchpad.net/ubuntu-push/bus/windowstack"
 	"launchpad.net/ubuntu-push/click"
+	"launchpad.net/ubuntu-push/click/cblacklist"
 	"launchpad.net/ubuntu-push/launch_helper"
 	"launchpad.net/ubuntu-push/logger"
 	"launchpad.net/ubuntu-push/messaging"
@@ -392,6 +393,8 @@
 	return svc.urlDispatcher.TestURL(app, notif.Card.Actions)
 }
 
+var isBlacklisted = cblacklist.IsBlacklisted
+
 func (svc *PostalService) messageHandler(app *click.AppId, nid string, output *launch_helper.HelperOutput) bool {
 	if output == nil || output.Notification == nil {
 		svc.Log.Debugf("skipping notification: nil.")
@@ -403,6 +406,11 @@
 		return false
 	}
 	if !svc.windowStack.IsAppFocused(app) {
+		if isBlacklisted(app) {
+			svc.Log.Debugf("notification skipped (except emblem counter) because app is blacklisted")
+			return svc.emblemCounter.Present(app, nid, output.Notification)
+		}
+
 		b := false
 		for _, p := range svc.Presenters {
 			// we don't want this to shortcut :)

=== modified file 'client/service/postal_test.go'
--- client/service/postal_test.go	2014-07-29 15:38:04 +0000
+++ client/service/postal_test.go	2014-08-04 15:37:24 +0000
@@ -141,6 +141,8 @@
 	winStackBus  bus.Endpoint
 	fakeLauncher *fakeHelperLauncher
 	getTempDir   func(string) (string, error)
+	oldIsBlisted func(*click.AppId) bool
+	blacklisted  bool
 }
 
 type ualPostalSuite struct {
@@ -155,6 +157,8 @@
 var _ = Suite(&trivialPostalSuite{})
 
 func (ps *postalSuite) SetUpTest(c *C) {
+	ps.oldIsBlisted = isBlacklisted
+	isBlacklisted = func(*click.AppId) bool { return ps.blacklisted }
 	ps.log = helpers.NewTestLogger(c, "debug")
 	ps.bus = testibus.NewTestingEndpoint(condition.Work(true), condition.Work(true))
 	ps.notifBus = testibus.NewTestingEndpoint(condition.Work(true), condition.Work(true))
@@ -163,6 +167,7 @@
 	ps.urlDispBus = testibus.NewTestingEndpoint(condition.Work(true), condition.Work(true))
 	ps.winStackBus = testibus.NewTestingEndpoint(condition.Work(true), condition.Work(true), []windowstack.WindowsInfo{})
 	ps.fakeLauncher = &fakeHelperLauncher{ch: make(chan []byte)}
+	ps.blacklisted = false
 
 	ps.getTempDir = launch_helper.GetTempDir
 	d := c.MkDir()
@@ -173,6 +178,7 @@
 }
 
 func (ps *postalSuite) TearDownTest(c *C) {
+	isBlacklisted = ps.oldIsBlisted
 	launch_helper.GetTempDir = ps.getTempDir
 }
 
@@ -779,3 +785,23 @@
 		c.Check(err, Equals, s.err, Commentf("iter %d", i))
 	}
 }
+
+func (ps *postalSuite) TestBlacklisted(c *C) {
+	svc := ps.replaceBuses(NewPostalService(nil, ps.log))
+	svc.Start()
+	ps.blacklisted = false
+
+	emb := &launch_helper.EmblemCounter{Count: 2, Visible: true}
+	card := &launch_helper.Card{Icon: "icon-value", Summary: "summary-value", Persist: true}
+	output := &launch_helper.HelperOutput{Notification: &launch_helper.Notification{Card: card}}
+	embOut := &launch_helper.HelperOutput{Notification: &launch_helper.Notification{EmblemCounter: emb}}
+	app := clickhelp.MustParseAppId("com.example.app_app_1.0")
+	// sanity check: things are presented as normal if blacklist == false
+	ps.blacklisted = false
+	c.Check(svc.messageHandler(app, "0", output), Equals, true)
+	c.Check(svc.messageHandler(app, "1", embOut), Equals, true)
+	ps.blacklisted = true
+	// and regular notifications (but not emblem counters) are supprsessed if blacklisted.
+	c.Check(svc.messageHandler(app, "2", output), Equals, false)
+	c.Check(svc.messageHandler(app, "3", embOut), Equals, true)
+}

=== modified file 'debian/changelog'
--- debian/changelog	2014-08-01 02:15:29 +0000
+++ debian/changelog	2014-08-04 15:37:24 +0000
@@ -1,3 +1,20 @@
+ubuntu-push (0.60-0ubuntu1) UNRELEASED; urgency=medium
+
+  [ Guillermo Gonzalez ]
+  * Add click hook to collect helpers data on install/update/etc and
+    support to read the helper cached data, when available, and only
+    refresh it when it changes.
+  * Include notification settings cleanup in the click install hook, and
+    rename it to click-hook
+
+  [ John R. Lenton ]
+  * For the gsettings interface: Improve, add tests, make design-compliant.
+
+  [Roberto Alsina]
+  * Query gsettings as to whether a notification should be presented.
+
+ -- John R. Lenton <[e-mail]>  Sat, 02 Aug 2014 01:42:17 +0200
+
 ubuntu-push (0.50+14.10.20140801-0ubuntu1) utopic; urgency=low
 
   * New rebuild forced
@@ -7,7 +24,7 @@
 ubuntu-push (0.50+14.10.20140729-0ubuntu1) utopic; urgency=medium
 
   [ Samuele Pedroni ]
-  * Cleanup and improve pos/Post tests
+  * Cleanup and improve post/Post tests
 
   [ Guillermo Gonzalez ]
   * Add a loop to cleanup MessagingMenu.notifications map when the

=== modified file 'debian/push-helper.hook'
--- debian/push-helper.hook	2014-07-23 13:56:09 +0000
+++ debian/push-helper.hook	2014-08-04 15:37:24 +0000
@@ -1,3 +1,4 @@
 Pattern: ${home}/.local/share/ubuntu-push-client/helpers/${id}.json
 User-Level: yes
 Hook-Name: push-helper
+Exec: /usr/lib/ubuntu-push-client/click-hook

=== modified file 'debian/ubuntu-push-client.install'
--- debian/ubuntu-push-client.install	2014-07-19 00:18:18 +0000
+++ debian/ubuntu-push-client.install	2014-08-04 15:37:24 +0000
@@ -4,5 +4,6 @@
 debian/exec-tool /usr/lib/${DEB_HOST_MULTIARCH}/ubuntu-app-launch/push-helper
 debian/push-helper.hook /usr/share/click/hooks
 signing-helper/signing-helper /usr/lib/ubuntu-push-client
+scripts/click-hook /usr/lib/ubuntu-push-client
 usr/bin/ubuntu-push => /usr/lib/ubuntu-push-client/ubuntu-push-client
 scripts/software-updates-helper.py => /usr/lib/ubuntu-push-client/legacy-helpers/ubuntu-system-settings

=== added directory 'docs'
=== added file 'docs/lowlevel.txt'
--- docs/lowlevel.txt	1970-01-01 00:00:00 +0000
+++ docs/lowlevel.txt	2014-08-04 15:37:24 +0000
@@ -0,0 +1,420 @@
+Ubuntu Push Client Developer Guide
+==================================
+
+:Version: 0.50+
+
+Introduction
+------------
+
+This document describes how to use the Ubuntu Push Client service from a platform integrator's point of view.
+Application developers are expected to use a much simpler API, in turn based on the lower-level API described here.
+
+The expected audience for this document is, therefore, either platform developers, or application developers who,
+for whatever reason, can't use or prefer not to use the available higher level APIs.
+
+---------
+
+Let's describe the push system by way of an example.
+
+Alice has written a chat application called Chatter. Using it, Bob can send messages to Carol and viceversa. Alice has a
+web application for it, so the way it works now is that Bob connects to the service, posts a message, and when Carol
+connects, she gets it. If Carol leaves the browser window open, it beeps when messages arrive.
+
+Now Alice wants to create an Ubuntu Touch app for Chatter, so she implements the same architecture using a client that
+does the same thing as the web browser. Sadly, since applications on Ubuntu Touch don't run continuously, messages are
+only delivered when Carol opens the app, and the user experience suffers.
+
+Using the Ubuntu Push Server, this problem is alleviated: the Chatter server will deliver the messages to the Ubuntu
+Push Server, which in turn will send it in an efficient manner to the Ubuntu Push Client running in Bob and Carol's
+devices. The user sees a notification (all without starting the app) and then can launch it if he's interested in
+reading messages at that point.
+
+Since the app is not started and messages are delivered oportunistically, this is both battery and bandwidth-efficient.
+
+.. figure:: push.svg
+
+The Ubuntu Push system provides:
+
+* A push server which receives **push messages** from the app servers, queues them and delivers them efficiently
+  to the devices.
+* A push client which receives those messages, queues messages to the app and displays notifications to the user
+
+The full lifecycle of a push message is:
+
+* Created in a application-specific server
+* Sent to the Ubuntu Push server, targeted at a user or user+device pair
+* Delivered to one or more Ubuntu devices
+* Passed through the application helper for processing
+* Notification displayed to the user (via different mechanisms)
+* Application Message queued for the app's use
+
+If the user interacts with the notification, the application is launched and should check its queue for messages
+it has to process.
+
+For the app developer, there are several components needed:
+
+* A server that sends the **push messages** to the Ubuntu Push server
+* Support in the client app for registering with the Ubuntu Push client
+* Support in the client app to react to **notifications** displayed to the user and process **application messages**
+* A helper program with application-specific knowledge that transforms **push messages** as needed.
+
+In the following sections, we'll see how to implement all the client side parts. For the application server, see the
+`Ubuntu Push Server API section <#ubuntu-push-server-api>`__
+
+The PushNotifications Service
+-----------------------------
+
+:Service: com.ubuntu.PushNotifications
+:Object path: /com/ubuntu/PushNotifications/QUOTED_PKGNAME
+
+The PushNotifications service handles registering the device with the Ubuntu Push service to enable delivery of messages to
+it.
+
+Each Ubuntu Touch package has to use a separate object path for security reasons, that's why the object path includes QUOTED_PKGNAME.
+For example, in the case of the music application, the package name is ``com.ubuntu.music`` and QUOTED_PKGNAME is com_2eubuntu_2emusic.
+Everything that is not a letter or digit has to be quoted as _XX where XX are the hex digits of the character. In practice,
+this means replacing "." with "_2e" and "-" with "_2f"
+
+.. note:: For applications that are not installed as part of click packages, the QUOTED_PKGNAME is "_" and the APP_ID when required is
+          _PACKAGENAME.
+
+          For example, for ubuntu-system-settins:
+
+          * QUOTED_PKGNAME is _
+          * APP_ID is _ubuntu-system-settings
+
+
+com.ubuntu.PushNotifications.Register
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``string Register(string APP_ID)``
+
+Example::
+
+	$ gdbus call --session --dest com.ubuntu.PushNotifications --object-path /com/ubuntu/PushNotifications/com_2eubuntu_2emusic \
+	--method com.ubuntu.PushNotifications.Register com.ubuntu.music_music
+
+	('LeA4tRQG9hhEkuhngdouoA==',)
+
+The Register method takes as argument the APP_ID (in the example, com.ubuntu.music_music) and returns a token identifying the user
+and device. For this to succeed the user **must** have an Ubuntu One account configured in the device.
+
+The APP_ID is as described in the `ApplicationId documentation <https://wiki.ubuntu.com/AppStore/Interfaces/ApplicationId>`__
+except that the version is treated as optional. Therefore both ``com.ubuntu.music_music`` and ``com.ubuntu.music_music_1.3.496``
+are valid. Keep in mind that while both versioned and unversioned APP_IDs are valid, they are still different and will affect
+which notifications are delivered to the application. Unversioned IDs mean the token will be the same after updates and the application
+will receive old notifications, while versioned IDs mean the app needs to explicitly ask to get older messages delivered.
+
+Register is idempotent, and calling it multiple times returns the same token.
+
+This token is later used by the application server to indicate the recipient of notifications.
+
+.. FIXME crosslink to server app
+
+.. note:: There is currently no way to send a push message to all of a user's devices. The application server has to send to
+          each registered device individually instead.
+
+com.ubuntu.PushNotifications.Unregister
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+``void Unregister(string APP_ID)``
+
+Example::
+
+	$ gdbus call --session --dest com.ubuntu.PushNotifications --object-path /com/ubuntu/PushNotifications/com_2eubuntu_2emusic \
+	--method com.ubuntu.PushNotifications.Unregister com.ubuntu.music_music
+
+The Unregister method invalidates the token obtained via `Register <#com-ubuntu-pushnotifications-register>`_  therefore disabling
+reception of push messages.
+
+The method takes as argument the APP_ID (in the example, com.ubuntu.music_music) and returns nothing.
+
+The APP_ID is as described in the `ApplicationId documentation <https://wiki.ubuntu.com/AppStore/Interfaces/ApplicationId>`__
+except that the version is treated as optional. Therefore both ``com.ubuntu.music_music`` and ``com.ubuntu.music_music_1.3.496``
+are valid.
+
+The Postal Service
+------------------
+
+:Service: com.ubuntu.Postal
+:Object path: /com/ubuntu/Postal/QUOTED_PKGNAME
+
+The Postal service delivers the actual messages to the applications. After the application is registered, the push client will begin
+delivering messages to the device, which will then (possibly) cause specific notifications to be presented to the user (message bubbles,
+sounds, haptic feedbak, etc.) Regardless of whether the user acknowledges those notifications or not, the payload of the push message
+is put in the Postal service for the application to pick up.
+
+Because user response to notifications can cause application activation, apps should check the status of the Postal service every time
+the application activates.
+
+com.ubuntu.Postal.Post
+~~~~~~~~~~~~~~~~~~~~~~
+
+``void Post(string APP_ID, string message)``
+
+Example::
+
+	gdbus call --session --dest com.ubuntu.Postal --object-path /com/ubuntu/Postal/com_2eubuntu_2emusic \
+	--method com.ubuntu.Postal.Post com.ubuntu.music_music \
+	'"{\"message\": \"foobar\", \"notification\":{\"card\": {\"summary\": \"yes\", \"body\": \"hello\", \"popup\": true, \"persist\": true}}}"'
+
+
+The arguments for the Post method are APP_ID (in the example, com.ubuntu.music_music) and a JSON string
+`describing a push message. <#push-message-format>`__
+
+Depending on the contents of the push message it may trigger user-facing notifications, and will queue a
+message for the app to get via the `PopAll <#com-ubuntu-postal-popalls>`__ method.
+
+The APP_ID is as described in the `ApplicationId documentation <https://wiki.ubuntu.com/AppStore/Interfaces/ApplicationId>`__
+except that the version is treated as optional. Therefore both ``com.ubuntu.music_music`` and ``com.ubuntu.music_music_1.3.496``
+are valid.
+
+.. note:: Post is useful as a unified frontend for notifications in Ubuntu Touch, since it wraps and abstracts several different APIs.
+
+com.ubuntu.Postal.PopAll
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``array{string} PopAll(string APP_ID)``
+
+Example::
+
+	$ gdbus call --session --dest com.ubuntu.Postal --object-path /com/ubuntu/Postal/com_2eubuntu_2emusic \
+	--method com.ubuntu.Postal.PopAll com.ubuntu.music_music
+
+	(['{"foo": "bar", ....}'],)
+
+The argument for the PopAll method is the APP_ID and it returns a list of strings, each string being a separate postal
+message, the "message" element of a helper's output fed from `Post <#com-ubuntu-postal-post>`__
+or from the Ubuntu Push service,
+
+Post Signal
+~~~~~~~~~~~
+
+``void Post(string APP_ID)``
+
+Every time a notification is posted, the postal service will emit the Post signal. Your app can connect to it to react to
+incoming notifications if it's running when they arrive. Remember that on Ubuntu Touch, the application lifecycle means
+it will often **not** be running when notifications arrive. If the application is in the foreground when a notification
+arrives, the notification **will not** be presented.
+
+The object path is similar to that of the Postal service methods, containing the QUOTED_PKGNAME.
+
+Persistent Notification Management
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Some notifications are persistent, meaning they don't disappear automatically. For those notifications, there is an API that
+allows the app to manage them without having to know the underlying details of the platform.
+
+On each notification there's an optional ``tag`` field, used for this purpose.
+
+``array(string) ListPersistent(string APP_ID)``
+
+Returns a list of the tags of notifications with the "persist" element set to true that are visible to the user right now.
+
+``void ClearPersistent(string APP_ID, [tag1, tag2,....])``
+
+Clears persistent notifications for that app by tag(s). If none given, match all.
+
+``void SetCounter(string APP_ID, int count int, bool visible)``
+
+Set the counter to the given values.
+
+
+Application Helpers
+-------------------
+
+The payload delivered to push-client will be passed onto a helper program that can modify it as needed before passing it onto
+the postal service (see `Helper Output Format <#helper-output-format>`__).
+
+The helper receives two arguments ``infile`` and ``outfile``. The message is delivered via ``infile`` and the transformed
+version is placed in ``outfile``.
+
+This is the simplest possible useful helper, which simply passes the message through unchanged::
+
+	#!/usr/bin/python3
+
+	import sys
+	f1, f2 = sys.argv[1:3]
+	open(f2, "w").write(open(f1).read())
+
+Helpers need to be added to the click package manifest::
+
+	{
+		"name": "com.ubuntu.developer.ralsina.hello",
+		"description": "description of hello",
+		"framework": "ubuntu-sdk-14.10-qml-dev2",
+		"architecture": "all",
+		"title": "hello",
+		"hooks": {
+			"hello": {
+				"apparmor": "hello.json",
+				"desktop": "hello.desktop"
+			},
+			"helloHelper": {
+				"apparmor": "helloHelper-apparmor.json",
+				"push-helper": "helloHelper.json"
+			}
+		},
+		"version": "0.2",
+		"maintainer": "Roberto Alsina <[e-mail]>"
+	}
+
+Here, we created a helloHelper entry in hooks that has an apparmor profile and an additional JSON file for the push-helper hook.
+
+helloHelper-apparmor.json must contain **only** the push-notification-client policy group::
+
+	{
+		"policy_groups": [
+			"push-notification-client"
+		],
+		"policy_version": 1.2
+	}
+
+And helloHelper.json must have at least a exec key with the path to the helper executable relative to the json, and optionally
+an app_id key containing the short id of one of the apps in the package (in the format packagename_appname without a version).
+If the app_id is not specified, the helper will be used for all apps in the package::
+
+	{
+		"exec": "helloHelper",
+		"app_id": "com.ubuntu.developer.ralsina.hello_hello"
+	}
+
+.. note:: For deb packages, helpers should be installed into /usr/lib/ubuntu-push-client/legacy-helpers/ as part of the package.
+
+Helper Output Format
+--------------------
+
+Helpers output has two parts, the postal message (in the "message" key) and a notification to be presented to the user (in the "notification" key).
+
+Here's a simple example::
+
+	{
+		"message": "foobar",
+		"notification": {
+			"tag": "foo",
+			"card": {
+				"summary": "yes",
+				"body": "hello",
+				"popup": true,
+				"persist": true
+			}
+			"sound": "buzz.mp3",
+			"vibrate": {
+				"pattern": [200, 100],
+				"duration": 200,
+				"repeat": 2
+			}
+			"emblem-counter": {
+				"count": 12,
+				"visible": true
+			}
+		}
+	}
+
+The notification can contain a **tag** field, which can later be used by the `persistent notification management API. <#persistent-notification-management>`__
+
+:message: (optional) A JSON object that is passed as-is to the application via PopAll.
+:notification: (optional) Describes the user-facing notifications triggered by this push message.
+
+The notification can contain a **card**. A card describes a specific notification to be given to the user,
+and has the following fields:
+
+:summary: (required) a title. The card will not be presented if this is missing.
+:body: longer text, defaults to empty.
+:actions: If empty (the default), a bubble notification is non-clickable.
+          If you add a URL, then bubble notifications are clickable and launch that URL. One use for this is using a URL like
+          ``appid://com.ubuntu.developer.ralsina.hello/hello/current-user-version`` which will switch to the app or launch
+          it if it's not running. See `URLDispatcher <https://wiki.ubuntu.com/URLDispatcher>`__ for more information.
+
+:icon: An icon relating to the event being notified. Defaults to empty (no icon);
+       a secondary icon relating to the application will be shown as well, regardless of this field.
+:timestamp: Seconds since the unix epoch, only used for persist (for now)
+:persist: Whether to show in notification centre; defaults to false
+:popup: Whether to show in a bubble. Users can disable this, and can easily miss them, so don't rely on it exclusively. Defaults to false.
+
+.. note:: Keep in mind that the precise way in which each field is presented to the user depends on factors such as
+          whether it's shown as a bubble or in the notification centre, or even the version of Ubuntu Touch the user
+          has on their device.
+
+The notification can contain a **sound** field. This is the path to a sound file. The user can disable it, so don't rely on it exclusively.
+Defaults to empty (no sound). This is a relative path, and will be looked up in (a) the application's .local/share/<pkgname>, and (b)
+standard xdg dirs.
+
+The notification can contain a **vibrate** field, causing haptic feedback, that has the following content:
+
+:pattern: a list of integers describing a vibration pattern.
+:duration: duration in milliseconds. Is equivalent to setting pattern to [duration], and overrides pattern.
+:repeat: number of times the pattern has to be repeated (defaults to 1, 0 is the same as 1).
+
+The notification can contain a **emblem-counter** field, with the following content:
+
+:count: a number to be displayed over the application's icon in the launcher.
+:visible: set to true to show the counter, or false to hide it.
+
+.. note:: Unlike other notifications, emblem-counter needs to be cleaned by the app itself.
+          Please see `the persistent notification management section. <#persistent-notification-management>`__
+
+.. FIXME crosslink to hello example app on each method
+
+Security
+~~~~~~~~
+
+To use the push API, applications need to request permission in their security profile, using something like this::
+
+	{
+		"policy_groups": [
+			"networking",
+			"push-notification-client"
+		],
+		"policy_version": 1.2
+	}
+
+
+Ubuntu Push Server API
+----------------------
+
+The Ubuntu Push server is located at https://push.ubuntu.com and has a single endpoint: ``/notify``.
+To notify a user, your application has to do a POST with ``Content-type: application/json``.
+
+Here is an example of the POST body using all the fields::
+
+	{
+		"appid": "com.ubuntu.music_music",
+		"expire_on": "2014-10-08T14:48:00.000Z",
+		"token": "LeA4tRQG9hhEkuhngdouoA==",
+		"clear_pending": true,
+		"replace_tag": "tagname",
+		"data": {
+			"message": "foobar",
+			"notification": {
+				"card": {
+					"summary": "yes",
+					"body": "hello",
+					"popup": true,
+					"persist": true
+				}
+				"sound": "buzz.mp3",
+				"tag": "foo",
+				"vibrate": {
+					"duration": 200,
+					"pattern": (200, 100),
+					"repeat": 2
+				}
+				"emblem-counter": {
+					"count": 12,
+					"visible": true
+				}
+			}
+		}
+	}
+
+
+:appid: ID of the application that will receive the notification, as described in the client side documentation.
+:expire_on: Expiration date/time for this message, in `ISO8601 Extendend format <http://en.wikipedia.org/wiki/ISO_8601>`__
+:token: The token identifying the user+device to which the message is directed, as described in the client side documentation.
+:clear_pending: Discards all previous pending notifications. Usually in response to getting a "too-many-pending" error.
+:replace_tag: If there's a pending notification with the same tag, delete it before queuing this new one.
+:data: A JSON object.
+
+In this example, data is `what a helper would output <#helper-output-format>`__ but that's not necessarily the case.
+The content of the data field will be passed to the helper application which **has** to produce output in that format.

=== added file 'docs/push.svg'
--- docs/push.svg	1970-01-01 00:00:00 +0000
+++ docs/push.svg	2014-08-04 15:37:24 +0000
@@ -0,0 +1,439 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
+   xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
+   width="41cm"
+   height="41cm"
+   viewBox="381 56 811 811"
+   id="svg2"
+   version="1.1"
+   inkscape:version="0.48.4 r9939"
+   sodipodi:docname="push.svg">
+  <metadata
+     id="metadata88">
+    <rdf:RDF>
+      <cc:Work
+         rdf:about="">
+        <dc:format>image/svg+xml</dc:format>
+        <dc:type
+           rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
+      </cc:Work>
+    </rdf:RDF>
+  </metadata>
+  <defs
+     id="defs86">
+    <marker
+       inkscape:stockid="Arrow1Lstart"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Lstart"
+       style="overflow:visible">
+      <path
+         id="path3984"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt"
+         transform="scale(0.8) translate(12.5,0)" />
+    </marker>
+    <marker
+       inkscape:stockid="Arrow1Lend"
+       orient="auto"
+       refY="0.0"
+       refX="0.0"
+       id="Arrow1Lend"
+       style="overflow:visible;">
+      <path
+         id="path3987"
+         d="M 0.0,0.0 L 5.0,-5.0 L -12.5,0.0 L 5.0,5.0 L 0.0,0.0 z "
+         style="fill-rule:evenodd;stroke:#000000;stroke-width:1.0pt;"
+         transform="scale(0.8) rotate(180) translate(12.5,0)" />
+    </marker>
+  </defs>
+  <sodipodi:namedview
+     pagecolor="#ffffff"
+     bordercolor="#666666"
+     borderopacity="1"
+     objecttolerance="10"
+     gridtolerance="10"
+     guidetolerance="10"
+     inkscape:pageopacity="0"
+     inkscape:pageshadow="2"
+     inkscape:window-width="1855"
+     inkscape:window-height="1056"
+     id="namedview84"
+     showgrid="false"
+     showguides="true"
+     inkscape:guide-bbox="true"
+     inkscape:zoom="0.62854741"
+     inkscape:cx="311.03462"
+     inkscape:cy="472.71845"
+     inkscape:window-x="65"
+     inkscape:window-y="24"
+     inkscape:window-maximized="1"
+     inkscape:current-layer="svg2">
+    <sodipodi:guide
+       orientation="0,1"
+       position="820.94047,984.81037"
+       id="guide4555" />
+  </sodipodi:namedview>
+  <line
+     style="fill:none;fill-opacity:0;stroke-width:2;stroke-dasharray:4;stroke:#000000;stroke-opacity:0.3037037"
+     x1="786"
+     y1="57"
+     x2="786"
+     y2="865"
+     id="line10" />
+  <line
+     style="fill:none;fill-opacity:0;stroke-width:2;stroke-dasharray:4;stroke:#000000;stroke-opacity:0.3037037"
+     x1="382"
+     y1="461"
+     x2="1190"
+     y2="461"
+     id="line12" />
+  <g
+     id="g6336"
+     transform="translate(695.42763,-47.960526)">
+    <rect
+       transform="matrix(0.55824934,0,0,0.55824934,381,56)"
+       y="124.296"
+       x="-641.16089"
+       height="87.503342"
+       width="240.23645"
+       id="rect6311"
+       style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:3;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:0.3037037;stroke-dasharray:none" />
+    <text
+       id="text14"
+       y="154.5843"
+       x="53.172604"
+       style="font-size:12.79979992px;font-style:normal;font-weight:normal;text-anchor:start;fill:#000000;font-family:sans-serif"
+       font-size="12.7998">
+      <tspan
+         id="tspan16"
+         y="154.5843"
+         x="53.172604">Server Side</tspan>
+    </text>
+  </g>
+  <g
+     id="g6331"
+     transform="translate(679.44079,315.29605)">
+    <rect
+       y="473.10199"
+       x="39.503288"
+       height="48.848682"
+       width="134.11185"
+       id="rect6311-7"
+       style="fill:#ffffff;fill-opacity:1;stroke:#000000;stroke-width:1.67474806;stroke-linejoin:round;stroke-miterlimit:4;stroke-opacity:0.3037037;stroke-dasharray:none" />
+    <text
+       id="text18"
+       y="502.29813"
+       x="72.128502"
+       style="font-size:12.79979992px;font-style:normal;font-weight:normal;text-anchor:start;fill:#000000;font-family:sans-serif"
+       font-size="12.7998">
+      <tspan
+         id="tspan20"
+         y="502.29813"
+         x="72.128502">Client Side</tspan>
+    </text>
+  </g>
+  <g
+     id="g30"
+     transform="translate(-13.351976,0)">
+    <rect
+       style="fill:#ffffff"
+       x="467.5"
+       y="594"
+       width="238"
+       height="152"
+       id="rect32" />
+    <rect
+       style="fill:none;stroke:#000000;stroke-width:2"
+       x="467.5"
+       y="594"
+       width="238"
+       height="152"
+       id="rect34" />
+  </g>
+  <text
+     font-size="12.7998"
+     style="font-size:12.79979992px;font-style:normal;font-weight:normal;text-anchor:start;fill:#000000;font-family:sans-serif"
+     x="535.41882"
+     y="674.77179"
+     id="text36">
+    <tspan
+       x="535.41882"
+       y="674.77179"
+       id="tspan38">Push Client</tspan>
+  </text>
+  <g
+     id="g3102"
+     transform="translate(-26.16447,-47.960526)">
+    <g
+       id="g40">
+      <rect
+         id="rect42"
+         height="84"
+         width="205"
+         y="725"
+         x="909.5"
+         style="fill:#ffffff" />
+      <rect
+         id="rect44"
+         height="84"
+         width="205"
+         y="725"
+         x="909.5"
+         style="fill:none;stroke:#000000;stroke-width:2" />
+    </g>
+    <text
+       id="text46"
+       y="770.53119"
+       x="972.96625"
+       style="font-size:12.79979992px;font-style:normal;font-weight:normal;text-anchor:start;fill:#000000;font-family:sans-serif"
+       font-size="12.7998">
+      <tspan
+         id="tspan48"
+         y="770.53119"
+         x="972.96625">Push Helper</tspan>
+    </text>
+  </g>
+  <g
+     id="g3972"
+     transform="translate(-10.46581,-2.6644735)">
+    <g
+       transform="translate(-15.098684,-4.4407892)"
+       id="g3095">
+      <g
+         id="g50">
+        <rect
+           style="fill:#ffffff"
+           x="908.90002"
+           y="534.70001"
+           width="205"
+           height="84"
+           id="rect52" />
+        <rect
+           style="fill:none;stroke:#000000;stroke-width:2"
+           x="908.90002"
+           y="534.70001"
+           width="205"
+           height="84"
+           id="rect54" />
+      </g>
+      <text
+         font-size="12.7998"
+         style="font-size:12.79979992px;font-style:normal;font-weight:normal;text-anchor:start;fill:#000000;font-family:sans-serif"
+         x="976.13806"
+         y="580.2312"
+         id="text56">
+        <tspan
+           x="976.13806"
+           y="580.2312"
+           id="tspan58">Application</tspan>
+      </text>
+    </g>
+  </g>
+  <text
+     xml:space="preserve"
+     style="font-size:15.63098145px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+     x="825.89801"
+     y="214.20395"
+     id="text4424"
+     sodipodi:linespacing="125%"><tspan
+       sodipodi:role="line"
+       id="tspan4426"
+       x="825.89801"
+       y="214.20395">/notify</tspan></text>
+  <g
+     id="g4546"
+     transform="translate(8.2993444,1.4703926)">
+    <g
+       transform="translate(-21.65132,-445.13816)"
+       id="g30-8-0">
+      <rect
+         id="rect32-6-7"
+         height="152"
+         width="238"
+         y="594"
+         x="467.5"
+         style="fill:#ffffff" />
+      <rect
+         id="rect34-62-9"
+         height="152"
+         width="238"
+         y="594"
+         x="467.5"
+         style="fill:none;stroke:#000000;stroke-width:2" />
+    </g>
+    <text
+       font-size="12.7998"
+       style="font-size:12.79979992px;font-style:normal;font-weight:normal;text-anchor:start;fill:#000000;font-family:sans-serif"
+       x="528.01489"
+       y="229.63364"
+       id="text80-9">
+      <tspan
+         x="528.01489"
+         y="229.63364"
+         id="tspan82-1">PushServer</tspan>
+    </text>
+  </g>
+  <g
+     id="g4994">
+    <g
+       transform="translate(399.33553,-442.47368)"
+       id="g30-8-0-2">
+      <rect
+         id="rect32-6-7-0"
+         height="152"
+         width="238"
+         y="594"
+         x="467.5"
+         style="fill:#ffffff" />
+      <rect
+         id="rect34-62-9-0"
+         height="152"
+         width="238"
+         y="594"
+         x="467.5"
+         style="fill:none;stroke:#000000;stroke-width:2" />
+    </g>
+    <text
+       font-size="12.7998"
+       style="font-size:12.79979992px;font-style:normal;font-weight:normal;text-anchor:start;fill:#000000;font-family:sans-serif"
+       x="950.25482"
+       y="232.29811"
+       id="text80-9-1">
+      <tspan
+         x="950.25482"
+         y="232.29811"
+         id="tspan82-1-7">App Server</tspan>
+    </text>
+  </g>
+  <path
+     style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:none;marker-end:url(#Arrow1Lend)"
+     d="M 870.28411,306.64076 557.36389,305.73534"
+     id="path5001"
+     inkscape:connector-type="polyline"
+     inkscape:connector-curvature="0"
+     inkscape:connection-start="#g4994"
+     inkscape:connection-start-point="d4"
+     inkscape:connection-end="#g4546"
+     inkscape:connection-end-point="d4"
+     transform="matrix(0.55824934,0,0,0.55824934,381,56)" />
+  <path
+     style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#Arrow1Lstart);marker-end:url(#Arrow1Lend)"
+     d="m 1083.4505,443.39743 0,401.37697"
+     id="path5003"
+     inkscape:connector-type="polyline"
+     inkscape:connector-curvature="0"
+     inkscape:connection-start="#g4994"
+     inkscape:connection-start-point="d4"
+     inkscape:connection-end="#g3972"
+     inkscape:connection-end-point="d4"
+     transform="matrix(0.55824934,0,0,0.55824934,381,56)" />
+  <path
+     style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:url(#Arrow1Lstart);marker-end:none"
+     d="M 899.8408,964.68112 557.36389,1048.0044"
+     id="path5005"
+     inkscape:connector-type="polyline"
+     inkscape:connector-curvature="0"
+     inkscape:connection-start="#g3972"
+     inkscape:connection-start-point="d4"
+     inkscape:connection-end="#g30"
+     inkscape:connection-end-point="d4"
+     transform="matrix(0.55824934,0,0,0.55824934,381,56)" />
+  <path
+     style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-miterlimit:4;stroke-opacity:1;stroke-dasharray:none;marker-start:none;marker-end:url(#Arrow1Lend)"
+     d="m 344.19749,441.25844 0,522.46863"
+     id="path5009"
+     inkscape:connector-type="polyline"
+     inkscape:connector-curvature="0"
+     inkscape:connection-start="#g4546"
+     inkscape:connection-start-point="d4"
+     inkscape:connection-end="#g30"
+     inkscape:connection-end-point="d4"
+     transform="matrix(0.55824934,0,0,0.55824934,381,56)" />
+  <text
+     xml:space="preserve"
+     style="font-size:15.63098145px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+     x="825.62708"
+     y="589.00653"
+     id="text6709"
+     sodipodi:linespacing="125%"><tspan
+       sodipodi:role="line"
+       id="tspan6711"
+       x="825.62708"
+       y="589.00653">PopAll</tspan></text>
+  <text
+     xml:space="preserve"
+     style="font-size:15.63098145px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+     x="491.13156"
+     y="412.44592"
+     id="text6717"
+     sodipodi:linespacing="125%"><tspan
+       sodipodi:role="line"
+       id="tspan6719"
+       x="491.13156"
+       y="412.44592">Push Notifications</tspan></text>
+  <text
+     xml:space="preserve"
+     style="font-size:15.63098145px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:center;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:middle;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+     x="1041.7894"
+     y="410.93091"
+     id="text6721"
+     sodipodi:linespacing="125%"><tspan
+       sodipodi:role="line"
+       id="tspan6723"
+       x="1041.7894"
+       y="410.93091">App-specific</tspan></text>
+  <text
+     xml:space="preserve"
+     style="font-size:22.32997322px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+     x="459.1579"
+     y="104.07236"
+     id="text3045"
+     sodipodi:linespacing="125%"><tspan
+       sodipodi:role="line"
+       id="tspan3047"
+       x="459.1579"
+       y="104.07236">Ubuntu Push System</tspan></text>
+  <text
+     xml:space="preserve"
+     style="font-size:22.32997322px;font-style:normal;font-weight:normal;line-height:125%;letter-spacing:0px;word-spacing:0px;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans"
+     x="919.22369"
+     y="101.4079"
+     id="text3049"
+     sodipodi:linespacing="125%"><tspan
+       sodipodi:role="line"
+       id="tspan3051"
+       x="919.22369"
+       y="101.4079">Application</tspan></text>
+  <path
+     style="fill:none;stroke:#000000;stroke-width:3;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Lend)"
+     d="m 556.83946,1145.6987 c 0,0 254.55518,138.4143 340.46755,62.0478"
+     id="path3051"
+     inkscape:connector-curvature="0"
+     transform="matrix(0.55824934,0,0,0.55824934,381,56)"
+     sodipodi:nodetypes="cc" />
+  <path
+     sodipodi:nodetypes="cc"
+     inkscape:connector-curvature="0"
+     id="path3053"
+     d="m 882.80916,712.85627 c 0,0 -142.10524,-77.26969 -190.06574,-34.63814"
+     style="fill:none;stroke:#000000;stroke-width:1.67474802000000000;stroke-linecap:butt;stroke-linejoin:miter;stroke-opacity:1;stroke-miterlimit:4;stroke-dasharray:none;marker-end:url(#Arrow1Lend)" />
+  <text
+     xml:space="preserve"
+     style="font-size:15.63098145px;font-style:normal;font-variant:normal;font-weight:normal;font-stretch:normal;text-align:start;line-height:125%;letter-spacing:0px;word-spacing:0px;writing-mode:lr-tb;text-anchor:start;fill:#000000;fill-opacity:1;stroke:none;font-family:Sans;-inkscape-font-specification:Sans"
+     x="811.3623"
+     y="717.78949"
+     id="text4019"
+     sodipodi:linespacing="125%"><tspan
+       sodipodi:role="line"
+       id="tspan4021"
+       x="811.3623"
+       y="717.78949">Call</tspan></text>
+</svg>

=== modified file 'launch_helper/cual/cual.go'
--- launch_helper/cual/cual.go	2014-07-18 20:45:21 +0000
+++ launch_helper/cual/cual.go	2014-08-04 15:37:24 +0000
@@ -31,6 +31,7 @@
 	"unsafe"
 
 	"launchpad.net/ubuntu-push/click"
+	"launchpad.net/ubuntu-push/launch_helper/helper_finder"
 	"launchpad.net/ubuntu-push/logger"
 )
 
@@ -77,7 +78,7 @@
 }
 
 func (hs *helperState) HelperInfo(app *click.AppId) (string, string) {
-	return app.Helper()
+	return helper_finder.Helper(app, hs.log)
 }
 
 func (hs *helperState) Launch(appId, exec, f1, f2 string) (string, error) {

=== added directory 'launch_helper/helper_finder'
=== added file 'launch_helper/helper_finder/helper_finder.go'
--- launch_helper/helper_finder/helper_finder.go	1970-01-01 00:00:00 +0000
+++ launch_helper/helper_finder/helper_finder.go	2014-08-04 15:37:24 +0000
@@ -0,0 +1,107 @@
+package helper_finder
+
+import (
+	"encoding/json"
+	"io/ioutil"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+
+	"launchpad.net/go-xdg/v0"
+
+	"launchpad.net/ubuntu-push/click"
+	"launchpad.net/ubuntu-push/logger"
+)
+
+type helperValue struct {
+	HelperId string `json:"helper_id"`
+	Exec     string `json:"exec"`
+}
+
+type hookFile struct {
+	AppId string `json:"app_id"`
+	Exec  string `json:"exec"`
+}
+
+var mapLock sync.Mutex
+var helpersInfo = make(map[string]helperValue)
+var helpersDataMtime time.Time
+
+var helpersDataPath = filepath.Join(xdg.Data.Home(), "ubuntu-push-client", "helpers_data.json")
+var hookPath = filepath.Join(xdg.Data.Home(), "ubuntu-push-client", "helpers")
+var hookExt = ".json"
+
+// helperFromHookfile figures out the app id and executable of the untrusted
+// helper for this app.
+func helperFromHookFile(app *click.AppId) (helperAppId string, helperExec string) {
+	matches, err := filepath.Glob(filepath.Join(hookPath, app.Package+"_*"+hookExt))
+	if err != nil {
+		return "", ""
+	}
+	var v hookFile
+	for _, m := range matches {
+		abs, err := filepath.EvalSymlinks(m)
+		if err != nil {
+			continue
+		}
+		data, err := ioutil.ReadFile(abs)
+		if err != nil {
+			continue
+		}
+		err = json.Unmarshal(data, &v)
+		if err != nil {
+			continue
+		}
+		if v.Exec != "" && (v.AppId == "" || v.AppId == app.Base()) {
+			basename := filepath.Base(m)
+			helperAppId = basename[:len(basename)-len(hookExt)]
+			helperExec = filepath.Join(filepath.Dir(abs), v.Exec)
+			return helperAppId, helperExec
+		}
+	}
+	return "", ""
+}
+
+// Helper figures out the id and executable of the untrusted
+// helper for this app.
+func Helper(app *click.AppId, log logger.Logger) (helperAppId string, helperExec string) {
+	if !app.Click {
+		return "", ""
+	}
+	fInfo, err := os.Stat(helpersDataPath)
+	if err != nil {
+		// cache file is missing, go via the slow route
+		log.Infof("Cache file not found, falling back to .json file lookup")
+		return helperFromHookFile(app)
+	}
+	// get the lock as the map can be changed while we read
+	mapLock.Lock()
+	defer mapLock.Unlock()
+	if helpersInfo == nil || fInfo.ModTime().After(helpersDataMtime) {
+		data, err := ioutil.ReadFile(helpersDataPath)
+		if err != nil {
+			return "", ""
+		}
+		err = json.Unmarshal(data, &helpersInfo)
+		if err != nil {
+			return "", ""
+		}
+		helpersDataMtime = fInfo.ModTime()
+	}
+	var info helperValue
+	info, ok := helpersInfo[app.Base()]
+	if !ok {
+		// ok, appid wasn't there, try with the package
+		info, ok = helpersInfo[app.Package]
+		if !ok {
+			return "", ""
+		}
+	}
+	if info.Exec != "" {
+		helperAppId = info.HelperId
+		helperExec = info.Exec
+		return helperAppId, helperExec
+	}
+	return "", ""
+}

=== added file 'launch_helper/helper_finder/helper_finder_test.go'
--- launch_helper/helper_finder/helper_finder_test.go	1970-01-01 00:00:00 +0000
+++ launch_helper/helper_finder/helper_finder_test.go	2014-08-04 15:37:24 +0000
@@ -0,0 +1,193 @@
+package helper_finder
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+	"time"
+
+	. "launchpad.net/gocheck"
+	helpers "launchpad.net/ubuntu-push/testing"
+
+	"launchpad.net/ubuntu-push/click"
+)
+
+type helperSuite struct {
+	oldHookPath        string
+	symlinkPath        string
+	oldHelpersDataPath string
+	log                *helpers.TestLogger
+}
+
+func TestHelperFinder(t *testing.T) { TestingT(t) }
+
+var _ = Suite(&helperSuite{})
+
+func (s *helperSuite) SetUpTest(c *C) {
+	s.oldHookPath = hookPath
+	hookPath = c.MkDir()
+	s.symlinkPath = c.MkDir()
+	s.oldHelpersDataPath = helpersDataPath
+	helpersDataPath = filepath.Join(c.MkDir(), "helpers_data.json")
+	s.log = helpers.NewTestLogger(c, "debug")
+}
+
+func (s *helperSuite) createHookfile(name string, content string) error {
+	symlink := filepath.Join(hookPath, name) + ".json"
+	filename := filepath.Join(s.symlinkPath, name)
+	f, err := os.Create(filename)
+	if err != nil {
+		return err
+	}
+	_, err = f.WriteString(content)
+	if err != nil {
+		return err
+	}
+	err = os.Symlink(filename, symlink)
+	if err != nil {
+		return err
+	}
+	return nil
+}
+
+func (s *helperSuite) createHelpersDatafile(content string) error {
+	f, err := os.Create(helpersDataPath)
+	if err != nil {
+		return err
+	}
+	_, err = f.WriteString(content)
+	if err != nil {
+		return err
+	}
+	return nil
+}
+
+func (s *helperSuite) TearDownTest(c *C) {
+	hookPath = s.oldHookPath
+	os.Remove(helpersDataPath)
+	helpersDataPath = s.oldHelpersDataPath
+	helpersDataMtime = time.Now().Add(-1 * time.Hour)
+	helpersInfo = nil
+}
+
+func (s *helperSuite) TestHelperBasic(c *C) {
+	c.Assert(s.createHelpersDatafile(`{"com.example.test": {"helper_id": "com.example.test_test-helper_1", "exec": "tsthlpr"}}`), IsNil)
+	app, err := click.ParseAppId("com.example.test_test-app_1")
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "com.example.test_test-helper_1")
+	c.Check(hex, Equals, "tsthlpr")
+}
+
+func (s *helperSuite) TestHelperFindsSpecific(c *C) {
+	fileContent := `{"com.example.test_test-other-app": {"exec": "aaaaaaa", "helper_id": "com.example.test_aaaa-helper_1"},
+    "com.example.test_test-app": {"exec": "tsthlpr", "helper_id": "com.example.test_test-helper_1"}}`
+	c.Assert(s.createHelpersDatafile(fileContent), IsNil)
+
+	app, err := click.ParseAppId("com.example.test_test-app_1")
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "com.example.test_test-helper_1")
+	c.Check(hex, Equals, "tsthlpr")
+}
+
+func (s *helperSuite) TestHelperCanFail(c *C) {
+	fileContent := `{"com.example.test_test-other-app": {"exec": "aaaaaaa", "helper_id": "com.example.test_aaaa-helper_1"}}`
+	c.Assert(s.createHelpersDatafile(fileContent), IsNil)
+	app, err := click.ParseAppId("com.example.test_test-app_1")
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "")
+	c.Check(hex, Equals, "")
+}
+
+func (s *helperSuite) TestHelperFailInvalidJson(c *C) {
+	fileContent := `{invalid json"com.example.test_test-other-app": {"exec": "aaaaaaa", "helper_id": "com.example.test_aaaa-helper_1"}}`
+	c.Assert(s.createHelpersDatafile(fileContent), IsNil)
+	app, err := click.ParseAppId("com.example.test_test-app_1")
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "")
+	c.Check(hex, Equals, "")
+}
+
+func (s *helperSuite) TestHelperFailMissingExec(c *C) {
+	fileContent := `{"com.example.test_test-app": {"helper_id": "com.example.test_aaaa-helper_1"}}`
+	c.Assert(s.createHelpersDatafile(fileContent), IsNil)
+	app, err := click.ParseAppId("com.example.test_test-app_1")
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "")
+	c.Check(hex, Equals, "")
+}
+
+func (s *helperSuite) TestHelperlegacy(c *C) {
+	appname := "ubuntu-system-settings"
+	app, err := click.ParseAppId("_" + appname)
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "")
+	c.Check(hex, Equals, "")
+}
+
+// Missing Cache file test
+
+func (s *helperSuite) TestHelperMissingCacheFile(c *C) {
+	c.Assert(s.createHookfile("com.example.test_test-helper_1", `{"exec": "tsthlpr"}`), IsNil)
+	app, err := click.ParseAppId("com.example.test_test-app_1")
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "com.example.test_test-helper_1")
+	c.Check(hex, Equals, filepath.Join(s.symlinkPath, "tsthlpr"))
+	c.Check(s.log.Captured(), Matches, ".*Cache file not found, falling back to .json file lookup\n")
+}
+
+func (s *helperSuite) TestHelperFromHookBasic(c *C) {
+	c.Assert(s.createHookfile("com.example.test_test-helper_1", `{"exec": "tsthlpr"}`), IsNil)
+	app, err := click.ParseAppId("com.example.test_test-app_1")
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "com.example.test_test-helper_1")
+	c.Check(hex, Equals, filepath.Join(s.symlinkPath, "tsthlpr"))
+}
+
+func (s *helperSuite) TestHelperFromHookFindsSpecific(c *C) {
+	// Glob() sorts, so the first one will come first
+	c.Assert(s.createHookfile("com.example.test_aaaa-helper_1", `{"exec": "aaaaaaa", "app_id": "com.example.test_test-other-app"}`), IsNil)
+	c.Assert(s.createHookfile("com.example.test_test-helper_1", `{"exec": "tsthlpr", "app_id": "com.example.test_test-app"}`), IsNil)
+	app, err := click.ParseAppId("com.example.test_test-app_1")
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "com.example.test_test-helper_1")
+	c.Check(hex, Equals, filepath.Join(s.symlinkPath, "tsthlpr"))
+}
+
+func (s *helperSuite) TestHelperFromHookCanFail(c *C) {
+	c.Assert(s.createHookfile("com.example.test_aaaa-helper_1", `{"exec": "aaaaaaa", "app_id": "com.example.test_test-other-app"}`), IsNil)
+	app, err := click.ParseAppId("com.example.test_test-app_1")
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "")
+	c.Check(hex, Equals, "")
+}
+
+func (s *helperSuite) TestHelperFromHookInvalidJson(c *C) {
+	c.Assert(s.createHookfile("com.example.test_aaaa-helper_1", `invalid json {"exec": "aaaaaaa", "app_id": "com.example.test_test-other-app"}`), IsNil)
+	app, err := click.ParseAppId("com.example.test_test-app_1")
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "")
+	c.Check(hex, Equals, "")
+}
+
+func (s *helperSuite) TestHelperFromHooFailBrokenSymlink(c *C) {
+	name := "com.example.test_aaaa-helper_1"
+	c.Assert(s.createHookfile(name, `{"exec": "aaaaaaa", "app_id": "com.example.test_test-other-app"}`), IsNil)
+	filename := filepath.Join(s.symlinkPath, name)
+	os.Remove(filename)
+	app, err := click.ParseAppId("com.example.test_test-app_1")
+	c.Assert(err, IsNil)
+	hid, hex := Helper(app, s.log)
+	c.Check(hid, Equals, "")
+	c.Check(hex, Equals, "")
+}

=== modified file 'launch_helper/kindpool_test.go'
--- launch_helper/kindpool_test.go	2014-07-29 15:24:01 +0000
+++ launch_helper/kindpool_test.go	2014-08-04 15:37:24 +0000
@@ -542,31 +542,28 @@
 }
 
 func (s *poolSuite) TestBigBacklogShrinks(c *C) {
+	oldBufSz := InputBufferSize
+	InputBufferSize = 0
+	defer func() { InputBufferSize = oldBufSz }()
 	s.pool.(*kindHelperPool).maxNum = 1
 	ch := s.pool.Start()
 	defer s.pool.Stop()
-	numBad := 10
 
 	app := clickhelp.MustParseAppId("com.example.test_test-app")
 	s.pool.Run("fake", &HelperInput{App: app, NotificationId: "0", Payload: []byte(`""`)})
-
-	for i := 0; i < numBad; i++ {
-		s.pool.Run("NOT-THERE", &HelperInput{App: app})
-	}
 	s.pool.Run("fake", &HelperInput{App: app, NotificationId: "1", Payload: []byte(`""`)})
 	s.pool.Run("fake", &HelperInput{App: app, NotificationId: "2", Payload: []byte(`""`)})
 	s.waitForArgs(c, "Launch")
 	go s.fakeLauncher.done("0")
-	// now we should get the fake + all the bad ones
-	for i := 0; i < numBad+1; i++ {
-		takeNext(ch, c)
-	}
+	takeNext(ch, c)
+	// so now there's one done, one "running", and one more waiting.
+	// kicking it forward one more notch before checking the logs:
 	s.waitForArgs(c, "Launch")
 	go s.fakeLauncher.done("1")
 	takeNext(ch, c)
-	// so now there's one good one "running", and one more waiting.
+	// (two done, one "running")
 	c.Check(s.log.Captured(), Matches, `(?ms).* shrunk to 1 entries\.$`)
-	// and the shrinker shrunk
+	// and the backlog shrinker shrunk the backlog
 	c.Check(s.log.Captured(), Matches, `(?ms).*copying backlog to avoid wasting too much space .*`)
 }
 

=== added file 'scripts/click-hook'
--- scripts/click-hook	1970-01-01 00:00:00 +0000
+++ scripts/click-hook	2014-08-04 15:37:24 +0000
@@ -0,0 +1,113 @@
+#!/usr/bin/python3
+"""Collect helpers hook data into a single json file"""
+
+import argparse
+import json
+import os
+import sys
+import time
+
+import xdg.BaseDirectory
+
+from gi.repository import GLib
+from gi.repository import Gio
+from gi.repository import Click
+
+hook_ext = '.json'
+
+
+def tup2variant(tup):
+    builder = GLib.VariantBuilder.new(GLib.VariantType.new("(ss)"))
+    builder.add_value(GLib.Variant.new_string(tup[0]))
+    builder.add_value(GLib.Variant.new_string(tup[1]))
+    return builder.end()
+
+
+def cleanup_settings():
+    clickdb = Click.DB.new()
+    clickdb.read()
+
+    pkgnames = []
+    for package in clickdb.get_packages(False):
+        pkgnames.append(package.get_property('package'))
+
+    settings = Gio.Settings.new('com.ubuntu.notifications.hub')
+    goodapps = GLib.VariantBuilder.new(GLib.VariantType.new("a(ss)"))
+
+    for appname in settings.get_value('blacklist').unpack():
+        if appname[0] in pkgnames:
+            goodapps.add_value(tup2variant(appname))
+        elif (appname[0] == appname[1]):
+            appinfo = Gio.DesktopAppInfo.new(appname[0] + ".desktop")
+            if not appinfo is None:
+                goodapps.add_value(tup2variant(appname))
+
+    settings.set_value('blacklist', goodapps.end())
+
+
+def collect_helpers(helpers_data_path, helpers_data_path_tmp, hooks_path):
+    helpers_data = {}
+    for hook_fname in os.listdir(hooks_path):
+        if not hook_fname.endswith(hook_ext):
+            continue
+        try:
+            with open(os.path.join(hooks_path, hook_fname), 'r') as fd:
+                data = json.load(fd)
+        except Exception:
+            continue
+        else:
+            helper_id = os.path.splitext(hook_fname)[0]
+            exec_path = data['exec']
+            if exec_path != "":
+                realpath = os.path.realpath(os.path.join(hooks_path,
+                                                         hook_fname))
+                exec_path = os.path.join(os.path.dirname(realpath), exec_path)
+            app_id = data.get('app_id', None)
+            if app_id is None:
+                # no app_id, use the package name from the helper_id
+                app_id = helper_id.split('_')[0]
+            elif app_id.count('_') >= 3:
+                # remove the version from the app_id
+                app_id = app_id.rsplit('_', 1)[0]
+            helpers_data[app_id] = {'exec': exec_path, 'helper_id': helper_id}
+
+    # write the collected data to a temp file and rename the original once
+    # everything is on disk
+    try:
+        tmp_filename = helpers_data_path_tmp % (time.time(),)
+        with open(tmp_filename, 'w') as dest:
+            json.dump(helpers_data, dest)
+            dest.flush()
+        os.rename(tmp_filename, helpers_data_path)
+    except Exception:
+        return True
+    return False
+
+
+def main(helpers_data_path=None, helpers_data_path_tmp=None, hooks_path=None):
+    collect_fail = collect_helpers(helpers_data_path, helpers_data_path_tmp,
+                                   hooks_path)
+    clean_settings_fail = False
+    try:
+        cleanup_settings()
+    except Exception:
+        clean_settings_fail = True
+    return int(collect_fail or clean_settings_fail)
+
+
+if __name__ == "__main__":
+    xdg_data_home = xdg.BaseDirectory.xdg_data_home
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument('-d', '--data-home',
+                        help='The Path to the (xdg) data home',
+                        default=xdg_data_home)
+    args = parser.parse_args()
+    xdg_data_home = args.data_home
+    helpers_data_path = os.path.join(xdg_data_home, 'ubuntu-push-client',
+                                     'helpers_data.json')
+    helpers_data_path_tmp = os.path.join(xdg_data_home, 'ubuntu-push-client',
+                                         '.helpers_data_%s.tmp')
+    hooks_path = os.path.join(xdg_data_home, 'ubuntu-push-client', 'helpers')
+    sys.exit(main(helpers_data_path=helpers_data_path,
+                  helpers_data_path_tmp=helpers_data_path_tmp,
+                  hooks_path=hooks_path))