Add sequence numbers for detecting dropped messages

Previously if a message was dropped, there was no way to know.  This
gives every message from the bus to the VM a sequence number; if any is
ever skipped, that tells the VM that some messages were not received.
This should rarely happen unless there is a flood of events, or a few
very large events, but if it does happen it's good to be able to know.

So far, no userspace library actually handles these sequence numbers,
but as far as I can tell none of the existing libraries are broken by
them either.

Author: dhouck

src/main/java/li/cil/oc2/api/README.md

@@ -91,9 +91,11 @@ the built-in `RedstoneInterfaceBlockEntity` device.
 - If subscriptions are used on or before OC2R version 2.2.12, they can cause a server crash if too many messages are
   sent at once. To be safe, do not send any event in the same tick as another message, or depend on a later minimum
   version of OC2R.
-- Right now, if a lot of messages are sent and the VM does not listen for them, some may be dropped, and there is no
-  indication to the device or VM when this happens. You cannot depend on the events being reliably delivered, and must
-  use some other communication channel if reliability is a requirement.
+- Right now, if a lot of messages are sent and the VM does not listen for them, some may be dropped; in theory the VM
+  can detect this, but none of the existing libraries do (see next point). You cannot depend on the events being
+  reliably delivered, and must use some other communication channel if reliability is a requirement.  A method call
+  should not have this issue unless the results and all the (subscribed to) events in that tick put together are more
+  than 4 KiB, though be aware that if the method call causes a state change, that might itself cause some events.
 - The on-the-"wire" event and subscription format is probably stable, but the VM's userspace python and lua libraries do
   not easily support them yet, and often silently discard events when expecting a different sort of message. Better
   support is actively being worked on.

src/main/java/li/cil/oc2/common/bus/RPCDeviceBusAdapter.java

@@ -58,6 +58,7 @@ public final class RPCDeviceBusAdapter implements Steppable, IEventSink {
     @Serialized private final ByteBuffer transmitBuffer; // for data written to device by VM
     @Serialized private ByteBuffer receiveBuffer; // for data written by device to VM
     @Serialized private MethodInvocation synchronizedInvocation; // pending main thread invocation
+    @Serialized private volatile long sequenceNumber = 0;
 
     ///////////////////////////////////////////////////////////////////
 
@@ -113,6 +114,7 @@ public void reset() {
         transmitBuffer.clear();
         receiveBuffer.clear();
         synchronizedInvocation = null;
+        sequenceNumber = 0;
     }
 
     public void pause() {
@@ -476,10 +478,11 @@ private void writeError(final String message) {
     }
 
     private void writeMessage(final String type, @Nullable final Object data) {
-        final String json = gson.toJson(new Message(type, data));
-        final byte[] bytes = json.getBytes();
-        final int messageLength = bytes.length + MESSAGE_DELIMITER.length * 2;
+        // Start synchronization here to also include sequenceNumber increment
         synchronized (receiveLock) {
+            final String json = gson.toJson(new Message(type, data, sequenceNumber++));
+            final byte[] bytes = json.getBytes();
+            final int messageLength = bytes.length + MESSAGE_DELIMITER.length * 2;
             if (receiveBuffer.remaining() < messageLength) {
                 // Decide whether to resize or not
                 // The current heuristic is to resize for a large message (because
@@ -493,7 +496,8 @@ private void writeMessage(final String type, @Nullable final Object data) {
                     reallocate ? "reallocating" : "ignoring");
 
                 if (!reallocate) {
-                    // Note: There is nothing that indicates to either the VM or the peripheral that a message was eaten
+                    // Return without writing anything.  We already incremented sequenceNumber, so the VM can know
+                    // something was missed when it reads the next message actually present.
                     return;
                 }
 
@@ -533,7 +537,7 @@ public record RPCDeviceWithIdentifier(UUID identifier, RPCDevice device) { }
 
     public record EmptyMethodGroup(String name) { }
 
-    public record Message(String type, @Nullable Object data) {
+    public record Message(String type, @Nullable Object data, long seq) {
         // Device -> VM
         public static final String MESSAGE_TYPE_LIST = "list";
         public static final String MESSAGE_TYPE_METHODS = "methods";

src/main/java/li/cil/oc2/common/serialization/gson/MessageJsonDeserializer.java

@@ -21,7 +21,8 @@ public RPCDeviceBusAdapter.Message deserialize(final JsonElement json, final Typ
             case RPCDeviceBusAdapter.Message.MESSAGE_TYPE_INVOKE_METHOD -> context.deserialize(jsonObject.getAsJsonObject("data"), RPCDeviceBusAdapter.MethodInvocation.class);
             default -> throw new JsonParseException(RPCDeviceBusAdapter.ERROR_UNKNOWN_MESSAGE_TYPE + messageType);
         };
+        final long messageSequenceNumber = jsonObject.has("seq") ? jsonObject.getAsJsonPrimitive("seq").getAsLong() : -1;
 
-        return new RPCDeviceBusAdapter.Message(messageType, messageData);
+        return new RPCDeviceBusAdapter.Message(messageType, messageData, messageSequenceNumber);
     }
 }