bramble-api/src/main/java/org/briarproject/bramble/api/battery/event/BatteryEvent.java

+package org.briarproject.bramble.api.battery.event;
+
+import org.briarproject.bramble.api.event.Event;
+
+/**
+ * An event that is broadcast when the device starts or stops charging.
+ */
+public class BatteryEvent extends Event {
+
+	private final boolean charging;
+
+	public BatteryEvent(boolean charging) {
+		this.charging = charging;
+	}
+
+	public boolean isCharging() {
+		return charging;
+	}
+}

bramble-api/src/main/java/org/briarproject/bramble/api/cleanup/CleanupHook.java

+package org.briarproject.bramble.api.cleanup;
+
+import org.briarproject.bramble.api.db.DatabaseComponent;
+import org.briarproject.bramble.api.db.DbException;
+import org.briarproject.bramble.api.db.Transaction;
+import org.briarproject.bramble.api.sync.GroupId;
+import org.briarproject.bramble.api.sync.MessageId;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.util.Collection;
+
+/**
+ * An interface for registering a hook with the {@link CleanupManager}
+ * that will be called when a message's cleanup deadline is reached.
+ */
+@NotNullByDefault
+public interface CleanupHook {
+
+	/**
+	 * Called when the cleanup deadlines of one or more messages are reached.
+	 * <p>
+	 * The callee is not required to delete the messages, but the hook won't be
+	 * called again for these messages unless another cleanup timer is set (see
+	 * {@link DatabaseComponent#setCleanupTimerDuration(Transaction, MessageId, long)}
+	 * and {@link DatabaseComponent#startCleanupTimer(Transaction, MessageId)}).
+	 */
+	void deleteMessages(Transaction txn, GroupId g,
+			Collection<MessageId> messageIds) throws DbException;
+}

bramble-api/src/main/java/org/briarproject/bramble/api/cleanup/CleanupManager.java

+package org.briarproject.bramble.api.cleanup;
+
+import org.briarproject.bramble.api.cleanup.event.CleanupTimerStartedEvent;
+import org.briarproject.bramble.api.crypto.SecretKey;
+import org.briarproject.bramble.api.db.DatabaseComponent;
+import org.briarproject.bramble.api.db.Transaction;
+import org.briarproject.bramble.api.lifecycle.LifecycleManager;
+import org.briarproject.bramble.api.sync.ClientId;
+import org.briarproject.bramble.api.sync.MessageId;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+/**
+ * The CleanupManager is responsible for tracking the cleanup deadlines of
+ * messages and passing them to their respective
+ * {@link CleanupHook CleanupHooks} when the deadlines are reached.
+ * <p>
+ * The CleanupManager responds to
+ * {@link CleanupTimerStartedEvent CleanupTimerStartedEvents} broadcast by the
+ * {@link DatabaseComponent}.
+ * <p>
+ * See {@link DatabaseComponent#setCleanupTimerDuration(Transaction, MessageId, long)},
+ * {@link DatabaseComponent#startCleanupTimer(Transaction, MessageId)},
+ * {@link DatabaseComponent#stopCleanupTimer(Transaction, MessageId)}.
+ */
+@NotNullByDefault
+public interface CleanupManager {
+
+	/**
+	 * When scheduling a cleanup task we overshoot the deadline by this many
+	 * milliseconds to reduce the number of tasks that need to be scheduled
+	 * when messages have cleanup deadlines that are close together.
+	 */
+	long BATCH_DELAY_MS = 1000;
+
+	/**
+	 * Registers a hook to be called when messages are due for cleanup.
+	 * This method should be called before
+	 * {@link LifecycleManager#startServices(SecretKey)}.
+	 */
+	void registerCleanupHook(ClientId c, int majorVersion,
+			CleanupHook hook);
+}

bramble-api/src/main/java/org/briarproject/bramble/api/cleanup/event/CleanupTimerStartedEvent.java

+package org.briarproject.bramble.api.cleanup.event;
+
+import org.briarproject.bramble.api.event.Event;
+import org.briarproject.bramble.api.sync.MessageId;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import javax.annotation.concurrent.Immutable;
+
+/**
+ * An event that is broadcast when a message's cleanup timer is started.
+ */
+@Immutable
+@NotNullByDefault
+public class CleanupTimerStartedEvent extends Event {
+
+	private final MessageId messageId;
+	private final long cleanupDeadline;
+
+	public CleanupTimerStartedEvent(MessageId messageId,
+			long cleanupDeadline) {
+		this.messageId = messageId;
+		this.cleanupDeadline = cleanupDeadline;
+	}
+
+	public MessageId getMessageId() {
+		return messageId;
+	}
+
+	public long getCleanupDeadline() {
+		return cleanupDeadline;
+	}
+}

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

+package org.briarproject.bramble.api.client;
+
+import org.briarproject.bramble.api.FormatException;
+import org.briarproject.bramble.api.data.BdfDictionary;
+import org.briarproject.bramble.api.data.BdfList;
+import org.briarproject.bramble.api.data.MetadataParser;
+import org.briarproject.bramble.api.db.DatabaseComponent;
+import org.briarproject.bramble.api.db.DbException;
+import org.briarproject.bramble.api.db.Metadata;
+import org.briarproject.bramble.api.db.Transaction;
+import org.briarproject.bramble.api.sync.InvalidMessageException;
+import org.briarproject.bramble.api.sync.Message;
+import org.briarproject.bramble.api.sync.validation.IncomingMessageHook;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import javax.annotation.concurrent.Immutable;
+
+@Immutable
+@NotNullByDefault
+public abstract class BdfIncomingMessageHook implements IncomingMessageHook {
+
+	protected final DatabaseComponent db;
+	protected final ClientHelper clientHelper;
+	protected final MetadataParser metadataParser;
+
+	protected BdfIncomingMessageHook(DatabaseComponent db,
+			ClientHelper clientHelper, MetadataParser metadataParser) {
+		this.db = db;
+		this.clientHelper = clientHelper;
+		this.metadataParser = metadataParser;
+	}
+
+	/**
+	 * Called once for each incoming message that passes validation.
+	 * <p>
+	 * If an unexpected exception occurs while handling data that is assumed
+	 * to be valid (e.g. locally created metadata), it may be sensible to
+	 * rethrow the unexpected exception as a DbException so that delivery is
+	 * attempted again at next startup. This will allow delivery to succeed if
+	 * the unexpected exception was caused by a bug that has subsequently been
+	 * fixed.
+	 *
+	 * @param txn A read-write transaction
+	 * @throws DbException if a database error occurs while delivering the
+	 * message. Delivery will be attempted again at next startup. Throwing
+	 * this exception has the same effect as returning
+	 * {@link DeliveryAction#DEFER}.
+	 * @throws FormatException if the message is invalid in the context of its
+	 * dependencies. The message and any dependents will be marked as invalid
+	 * and deleted along with their metadata. Throwing this exception has the
+	 * same effect as returning {@link DeliveryAction#REJECT}.
+	 */
+	protected abstract DeliveryAction incomingMessage(Transaction txn,
+			Message m, BdfList body, BdfDictionary meta)
+			throws DbException, FormatException;
+
+	@Override
+	public DeliveryAction incomingMessage(Transaction txn, Message m,
+			Metadata meta) throws DbException, InvalidMessageException {
+		try {
+			BdfList body = clientHelper.toList(m);
+			BdfDictionary metaDictionary = metadataParser.parse(meta);
+			return incomingMessage(txn, m, body, metaDictionary);
+		} catch (FormatException e) {
+			throw new InvalidMessageException(e);
+		}
+	}
+}

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

+package org.briarproject.bramble.api.client;
+
+import org.briarproject.bramble.api.data.BdfDictionary;
+import org.briarproject.bramble.api.sync.MessageId;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.util.Collection;
+import java.util.Collections;
+
+import javax.annotation.concurrent.Immutable;
+
+@Immutable
+@NotNullByDefault
+public class BdfMessageContext {
+
+	private final BdfDictionary dictionary;
+	private final Collection<MessageId> dependencies;
+
+	public BdfMessageContext(BdfDictionary dictionary,
+			Collection<MessageId> dependencies) {
+		this.dictionary = dictionary;
+		this.dependencies = dependencies;
+	}
+
+	public BdfMessageContext(BdfDictionary dictionary) {
+		this(dictionary, Collections.emptyList());
+	}
+
+	public BdfDictionary getDictionary() {
+		return dictionary;
+	}
+
+	public Collection<MessageId> getDependencies() {
+		return dependencies;
+	}
+}

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

+package org.briarproject.bramble.api.client;
+
+import org.briarproject.bramble.api.FormatException;
+import org.briarproject.bramble.api.data.BdfList;
+import org.briarproject.bramble.api.data.MetadataEncoder;
+import org.briarproject.bramble.api.db.Metadata;
+import org.briarproject.bramble.api.sync.Group;
+import org.briarproject.bramble.api.sync.InvalidMessageException;
+import org.briarproject.bramble.api.sync.Message;
+import org.briarproject.bramble.api.sync.MessageContext;
+import org.briarproject.bramble.api.sync.validation.MessageValidator;
+import org.briarproject.bramble.api.system.Clock;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+import java.util.logging.Logger;
+
+import javax.annotation.concurrent.Immutable;
+
+import static java.util.logging.Logger.getLogger;
+import static org.briarproject.bramble.api.transport.TransportConstants.MAX_CLOCK_DIFFERENCE;
+
+@Immutable
+@NotNullByDefault
+public abstract class BdfMessageValidator implements MessageValidator {
+
+	protected static final Logger LOG =
+			getLogger(BdfMessageValidator.class.getName());
+
+	protected final ClientHelper clientHelper;
+	protected final MetadataEncoder metadataEncoder;
+	protected final Clock clock;
+	protected final boolean canonical;
+
+	/**
+	 * Transitional alternative to
+	 * {@link #BdfMessageValidator(ClientHelper, MetadataEncoder, Clock)} that
+	 * accepts messages in non-canonical form, for backward compatibility.
+	 */
+	@Deprecated
+	protected BdfMessageValidator(ClientHelper clientHelper,
+			MetadataEncoder metadataEncoder, Clock clock, boolean canonical) {
+		this.clientHelper = clientHelper;
+		this.metadataEncoder = metadataEncoder;
+		this.clock = clock;
+		this.canonical = canonical;
+	}
+
+	protected BdfMessageValidator(ClientHelper clientHelper,
+			MetadataEncoder metadataEncoder, Clock clock) {
+		this(clientHelper, metadataEncoder, clock, true);
+	}
+
+	protected abstract BdfMessageContext validateMessage(Message m, Group g,
+			BdfList body) throws InvalidMessageException, FormatException;
+
+	@Override
+	public MessageContext validateMessage(Message m, Group g)
+			throws InvalidMessageException {
+		// Reject the message if it's too far in the future
+		long now = clock.currentTimeMillis();
+		if (m.getTimestamp() - now > MAX_CLOCK_DIFFERENCE) {
+			throw new InvalidMessageException(
+					"Timestamp is too far in the future");
+		}
+		try {
+			BdfList bodyList = clientHelper.toList(m, canonical);
+			BdfMessageContext result = validateMessage(m, g, bodyList);
+			Metadata meta = metadataEncoder.encode(result.getDictionary());
+			return new MessageContext(meta, result.getDependencies());
+		} catch (FormatException e) {
+			throw new InvalidMessageException(e);
+		}
+	}
+}

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

+package org.briarproject.bramble.api.client;
+
+public interface ContactGroupConstants {
+
+	/**
+	 * Group metadata key for associating a contact ID with a contact group.
+	 */
+	String GROUP_KEY_CONTACT_ID = "contactId";
+}

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

+package org.briarproject.bramble.api.client;
+
+import org.briarproject.bramble.api.contact.Contact;
+import org.briarproject.bramble.api.identity.AuthorId;
+import org.briarproject.bramble.api.sync.ClientId;
+import org.briarproject.bramble.api.sync.Group;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+@NotNullByDefault
+public interface ContactGroupFactory {
+
+	/**
+	 * Creates a group that is not shared with any contacts.
+	 */
+	Group createLocalGroup(ClientId clientId, int majorVersion);
+
+	/**
+	 * Creates a group for the given client to share with the given contact.
+	 */
+	Group createContactGroup(ClientId clientId, int majorVersion,
+			Contact contact);
+
+	/**
+	 * Creates a group for the given client to share between the given authors
+	 * identified by their AuthorIds.
+	 */
+	Group createContactGroup(ClientId clientId, int majorVersion,
+			AuthorId authorId1, AuthorId authorId2);
+
+}

bramble-api/src/main/java/org/briarproject/bramble/api/connection/ConnectionManager.java

+package org.briarproject.bramble.api.connection;
+
+import org.briarproject.bramble.api.contact.ContactId;
+import org.briarproject.bramble.api.contact.PendingContactId;
+import org.briarproject.bramble.api.plugin.TransportConnectionReader;
+import org.briarproject.bramble.api.plugin.TransportConnectionWriter;
+import org.briarproject.bramble.api.plugin.TransportId;
+import org.briarproject.bramble.api.plugin.duplex.DuplexTransportConnection;
+import org.briarproject.bramble.api.sync.OutgoingSessionRecord;
+import org.briarproject.nullsafety.NotNullByDefault;
+
+@NotNullByDefault
+public interface ConnectionManager {
+
+	/**
+	 * Manages an incoming connection from a contact over a simplex transport.
+	 */
+	void manageIncomingConnection(TransportId t, TransportConnectionReader r);
+
+	/**
+	 * Manages an incoming connection from a contact via a mailbox.
+	 * <p>
+	 * This method does not mark the tag as recognised until after the data
+	 * has been read from the {@link TransportConnectionReader}, at which
+	 * point the {@link TagController} is called to decide whether the tag
+	 * should be marked as recognised.
+	 */
+	void manageIncomingConnection(TransportId t, TransportConnectionReader r,
+			TagController c);
+
+	/**
+	 * Manages an incoming connection from a contact over a duplex transport.
+	 */
+	void manageIncomingConnection(TransportId t, DuplexTransportConnection d);
+
+	/**
+	 * Manages an incoming handshake connection from a pending contact over a
+	 * duplex transport.
+	 */
+	void manageIncomingConnection(PendingContactId p, TransportId t,
+			DuplexTransportConnection d);
+
+	/**
+	 * Manages an outgoing connection to a contact over a simplex transport.
+	 */
+	void manageOutgoingConnection(ContactId c, TransportId t,
+			TransportConnectionWriter w);
+
+	/**
+	 * Manages an outgoing connection to a contact via a mailbox. The IDs of
+	 * any messages sent or acked are added to the given
+	 * {@link OutgoingSessionRecord}.
+	 */
+	void manageOutgoingConnection(ContactId c, TransportId t,
+			TransportConnectionWriter w, OutgoingSessionRecord sessionRecord);
+
+	/**
+	 * Manages an outgoing connection to a contact over a duplex transport.
+	 */
+	void manageOutgoingConnection(ContactId c, TransportId t,
+			DuplexTransportConnection d);
+
+	/**
+	 * Manages an outgoing handshake connection to a pending contact over a
+	 * duplex transport.
+	 */
+	void manageOutgoingConnection(PendingContactId p, TransportId t,
+			DuplexTransportConnection d);
+
+	/**
+	 * An interface for controlling whether a tag should be marked as
+	 * recognised.
+	 */
+	interface TagController {
+		/**
+		 * This method is only called if a tag was read from the corresponding
+		 * {@link TransportConnectionReader} and recognised.
+		 *
+		 * @param exception True if an exception was thrown while reading from
+		 * the {@link TransportConnectionReader}, after successfully reading
+		 * and recognising the tag.
+		 * @return True if the tag should be marked as recognised.
+		 */
+		boolean shouldMarkTagAsRecognised(boolean exception);
+	}
+}

bramble-api/src/main/java/org/briarproject/bramble/api/connection/InterruptibleConnection.java

+package org.briarproject.bramble.api.connection;
+
+import org.briarproject.nullsafety.NotNullByDefault;
+
+/**
+ * A duplex sync connection that can be closed by interrupting its outgoing
+ * sync session.
+ */
+@NotNullByDefault
+public interface InterruptibleConnection {
+
+	/**
+	 * Interrupts the connection's outgoing sync session. If the underlying
+	 * transport connection is alive and the remote peer is cooperative, this
+	 * should result in both sync sessions ending and the connection being
+	 * cleanly closed.
+	 */
+	void interruptOutgoingSession();
+}