Implement the Mailbox property client

bramble-api/src/main/java/org/briarproject/bramble/api/client/ClientHelper.java

@@ -9,6 +9,7 @@ import org.briarproject.bramble.api.data.BdfList;
 import org.briarproject.bramble.api.db.DbException;
 import org.briarproject.bramble.api.db.Transaction;
 import org.briarproject.bramble.api.identity.Author;
+import org.briarproject.bramble.api.mailbox.MailboxPropertiesUpdate;
 import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
 import org.briarproject.bramble.api.plugin.TransportId;
 import org.briarproject.bramble.api.properties.TransportProperties;
@@ -20,6 +21,8 @@ import java.security.GeneralSecurityException;
 import java.util.Collection;
 import java.util.Map;
 
+import javax.annotation.Nullable;
+
 @NotNullByDefault
 public interface ClientHelper {
 
@@ -123,6 +126,18 @@ public interface ClientHelper {
 	Map<TransportId, TransportProperties> parseAndValidateTransportPropertiesMap(
 			BdfDictionary properties) throws FormatException;
 
+	/**
+	 * Parse and validate the property dictionary of a Mailbox property update
+	 * message.
+	 *
+	 * @return the properties for using the Mailbox, or null if there is no
+	 * Mailbox available
+	 * @throws FormatException if the properties are not valid
+	 */
+	@Nullable
+	MailboxPropertiesUpdate parseAndValidateMailboxPropertiesUpdate(
+			BdfDictionary properties) throws FormatException;
+
 	/**
 	 * Retrieves the contact ID from the group metadata of the given contact
 	 * group.

bramble-api/src/main/java/org/briarproject/bramble/api/mailbox/MailboxProperties.java

@@ -23,6 +23,11 @@ public class MailboxProperties {
 		return baseUrl;
 	}
 
+	public String getOnion() {
+		return baseUrl.replaceFirst("^http://", "")
+				.replaceFirst("\\.onion$", "");
+	}
+
 	public MailboxAuthToken getAuthToken() {
 		return authToken;
 	}

bramble-api/src/main/java/org/briarproject/bramble/api/mailbox/MailboxPropertiesUpdate.java

@@ -0,0 +1,41 @@
+package org.briarproject.bramble.api.mailbox;
+
+import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
+
+import javax.annotation.concurrent.Immutable;
+
+@Immutable
+@NotNullByDefault
+public class MailboxPropertiesUpdate {
+
+	private final String onionAddress;
+	private final MailboxAuthToken authToken;
+	private final MailboxFolderId inboxId;
+	private final MailboxFolderId outboxId;
+
+	public MailboxPropertiesUpdate(String onionAddress,
+			MailboxAuthToken authToken, MailboxFolderId inboxId,
+			MailboxFolderId outboxId) {
+		this.onionAddress = onionAddress;
+		this.authToken = authToken;
+		this.inboxId = inboxId;
+		this.outboxId = outboxId;
+	}
+
+	public String getOnionAddress() {
+		return onionAddress;
+	}
+
+	public MailboxAuthToken getAuthToken() {
+		return authToken;
+	}
+
+	public MailboxFolderId getInboxId() {
+		return inboxId;
+	}
+
+	public MailboxFolderId getOutboxId() {
+		return outboxId;
+	}
+
+}

bramble-api/src/main/java/org/briarproject/bramble/api/mailbox/MailboxPropertyManager.java

@@ -0,0 +1,67 @@
+package org.briarproject.bramble.api.mailbox;
+
+import org.briarproject.bramble.api.contact.ContactId;
+import org.briarproject.bramble.api.db.DbException;
+import org.briarproject.bramble.api.db.Transaction;
+import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
+import org.briarproject.bramble.api.sync.ClientId;
+
+import javax.annotation.Nullable;
+
+@NotNullByDefault
+public interface MailboxPropertyManager {
+
+	/**
+	 * The unique ID of the mailbox property client.
+	 */
+	ClientId CLIENT_ID =
+			new ClientId("org.briarproject.bramble.mailbox.properties");
+
+	/**
+	 * The current major version of the mailbox property client.
+	 */
+	int MAJOR_VERSION = 0;
+
+	/**
+	 * The current minor version of the mailbox property client.
+	 */
+	int MINOR_VERSION = 0;
+
+	/**
+	 * The number of properties required for a (non-empty) update message.
+	 */
+	int PROP_COUNT = 4;
+
+	/**
+	 * The required properties of a non-empty update message.
+	 */
+	String PROP_KEY_ONIONADDRESS = "onionAddress";
+	String PROP_KEY_AUTHTOKEN = "authToken";
+	String PROP_KEY_INBOXID = "inboxId";
+	String PROP_KEY_OUTBOXID = "outboxId";
+
+	/**
+	 * Length of the Onion Address property.
+	 */
+	int PROP_ONIONADDRESS_LENGTH = 56;
+
+	/**
+	 * Message metadata key for the version number of a local or remote update,
+	 * as a BDF long.
+	 */
+	String MSG_KEY_VERSION = "version";
+
+	/**
+	 * Message metadata key for whether an update is local or remote, as a BDF
+	 * boolean.
+	 */
+	String MSG_KEY_LOCAL = "local";
+
+	@Nullable
+	MailboxPropertiesUpdate getLocalProperties(Transaction txn, ContactId c)
+			throws DbException;
+
+	@Nullable
+	MailboxPropertiesUpdate getRemoteProperties(Transaction txn, ContactId c)
+			throws DbException;
+}

bramble-api/src/main/java/org/briarproject/bramble/api/mailbox/MailboxSettingsManager.java

@@ -1,8 +1,10 @@
 package org.briarproject.bramble.api.mailbox;
 
 import org.briarproject.bramble.api.contact.ContactId;
+import org.briarproject.bramble.api.crypto.SecretKey;
 import org.briarproject.bramble.api.db.DbException;
 import org.briarproject.bramble.api.db.Transaction;
+import org.briarproject.bramble.api.lifecycle.LifecycleManager;
 import org.briarproject.bramble.api.nullsafety.NotNullByDefault;
 
 import javax.annotation.Nullable;
@@ -10,6 +12,13 @@ import javax.annotation.Nullable;
 @NotNullByDefault
 public interface MailboxSettingsManager {
 
+	/**
+	 * Registers a hook to be called when a mailbox has been paired or unpaired.
+	 * This method should be called before
+	 * {@link LifecycleManager#startServices(SecretKey)}.
+	 */
+	void registerMailboxHook(MailboxHook hook);
+
 	@Nullable
 	MailboxProperties getOwnMailboxProperties(Transaction txn)
 			throws DbException;
@@ -30,4 +39,22 @@ public interface MailboxSettingsManager {
 
 	@Nullable
 	String getPendingUpload(Transaction txn, ContactId id) throws DbException;
+
+	interface MailboxHook {
+		/**
+		 * Called when Briar is paired with a mailbox
+		 *
+		 * @param txn A read-write transaction
+		 * @param ownOnion Our new mailbox's onion (56 base32 chars)
+		 */
+		void mailboxPaired(Transaction txn, String ownOnion)
+				throws DbException;
+
+		/**
+		 * Called when the mailbox is unpaired
+		 *
+		 * @param txn A read-write transaction
+		 */
+		void mailboxUnpaired(Transaction txn) throws DbException;
+	}
 }

bramble-api/src/test/java/org/briarproject/bramble/test/TestUtils.java

@@ -16,6 +16,7 @@ import org.briarproject.bramble.api.identity.Author;
 import org.briarproject.bramble.api.identity.AuthorId;
 import org.briarproject.bramble.api.identity.Identity;
 import org.briarproject.bramble.api.identity.LocalAuthor;
+import org.briarproject.bramble.api.mailbox.MailboxPropertiesUpdate;
 import org.briarproject.bramble.api.plugin.TransportId;
 import org.briarproject.bramble.api.properties.TransportProperties;
 import org.briarproject.bramble.api.sync.ClientId;
@@ -39,6 +40,8 @@ import java.util.Map;
 import java.util.Random;
 import java.util.concurrent.atomic.AtomicInteger;
 
+import javax.annotation.Nullable;
+
 import static java.util.Arrays.asList;
 import static org.briarproject.bramble.api.crypto.CryptoConstants.MAX_AGREEMENT_PUBLIC_KEY_BYTES;
 import static org.briarproject.bramble.api.crypto.CryptoConstants.MAX_SIGNATURE_PUBLIC_KEY_BYTES;
@@ -271,4 +274,17 @@ public class TestUtils {
 		return optionalTests != null &&
 				asList(optionalTests.split(",")).contains(testClass.getName());
 	}
+
+	public static boolean mailboxPropertiesUpdateEqual(
+			@Nullable MailboxPropertiesUpdate a,
+			@Nullable MailboxPropertiesUpdate b) {
+		if (a == null || b == null) {
+			return a == b;
+		}
+		return a.getOnionAddress().equals(b.getOnionAddress()) &&
+				a.getAuthToken().equals(b.getAuthToken()) &&
+				a.getInboxId().equals(b.getInboxId()) &&
+				a.getOutboxId().equals(b.getOutboxId());
+	}
+
 }