Add a format to the LiveObjects encoding and decoding methods

The plugin will use this to apply the spec's rules (see [1]) regarding
the encoding and decoding of binary data.

This was initially generated by Cursor at my instructions, but I ended
up rewriting most of the documentation it generated because it didn't
have enough context to understand how the plugin would use the format.

[1] ably/specification#335

Author: lawrence-forooghian

AblyPlugin/include/APEncodingFormat.h

@@ -0,0 +1,16 @@
+/// The wire format to which a plugin object should encode an object or from which a plugin should be decode an object.
+///
+/// The requirements for encoding to and decoding from each format are as follows:
+///
+/// - `APEncodingFormatJSON`:
+///   - Encoding: Plugins should generate an object that ably-cocoa can pass to Foundation's `JSONSerialization.data(withJSONObject:,…)`.
+///   - Decoding: Plugins should expect to find the same types of values as you would in the output of Foundation's `JSONSerialization`.
+/// - `APEncodingFormatMessagePack`:
+///   - Encoding: As for `APEncodingFormatJSON`, but arrays and dictionaries are allowed to additionally contain `NSData` values.
+///   - Decoding: As for `APEncodingFormatJSON`, but arrays and dictionaries may also additionally contain `NSData` values.
+///
+/// We intentionally use a closed enum so that plugins do not have to include an `@unknown default` (since there is no sensible default for them to use; if we introduce a new encoding format in the future then we will have to define new logic — and since it's a closed enum, a new enum).
+typedef NS_CLOSED_ENUM(NSInteger, APEncodingFormat) {
+    APEncodingFormatJSON NS_SWIFT_NAME(json),
+    APEncodingFormatMessagePack
+} NS_SWIFT_NAME(EncodingFormat);

AblyPlugin/include/APLiveObjectsPlugin.h

@@ -1,4 +1,5 @@
 #import <Foundation/Foundation.h>
+#import "APEncodingFormat.h"
 
 @class ARTRealtimeChannel;
 @class ARTErrorInfo;
@@ -35,21 +36,25 @@ NS_SWIFT_SENDABLE
 /// Decodes an `ObjectMessage` received over the wire.
 ///
 /// Parameters:
-/// - serialized: A dictionary that contains the representation of the `ObjectMessage` received over the wire. You should expect to find the same types of values here as you would in the output of Foundation's `JSONSerialization`.
+/// - serialized: A dictionary that contains the representation of the `ObjectMessage` received over the wire. To find out what kinds of values you should expect to find here for a given `format`, see th decoding rules described in `APEncodingFormat`.
 /// - context: Contains information that may be needed in the decoding, such as information about the containing `ProtocolMessage`.
+/// - format: The format that was used to create `serialized`, and whose rules should be used when decoding the `ObjectMessage`.
 ///
 /// Returns: A `ObjectMessageProtocol` object that ably-cocoa can later pass to this plugin's `-handleObjectProtocolMessageWithObjectMessages:channel:` method, or `nil` if decoding fails (in which case `error` must be populated).
 - (nullable id<APObjectMessageProtocol>)decodeObjectMessage:(NSDictionary<NSString *, id> *)serialized
                                                     context:(id<APDecodingContextProtocol>)context
+                                                     format:(APEncodingFormat)format
                                                       error:(ARTErrorInfo *_Nullable *_Nullable)error;
 
 /// Encodes an `ObjectMessage` to be sent over the wire.
 ///
 /// Parameters:
 /// - objectMessage: An `ObjectMessage` that this plugin earlier passed to `APPluginAPI`'s `-sendStateWithObjectMessages:channel:completion:`.
+/// - format: The format whose rules should be used when encoding the `ObjectMessage`.
 ///
-/// Returns: An object that ably-cocoa can pass to Foundation's `JSONSerialization`.
-- (NSDictionary<NSString *, id> *)encodeObjectMessage:(id<APObjectMessageProtocol>)objectMessage;
+/// Returns: See the encoding rules described in `APEncodingFormat`.
+- (NSDictionary<NSString *, id> *)encodeObjectMessage:(id<APObjectMessageProtocol>)objectMessage
+                                               format:(APEncodingFormat)format;
 
 /// Called when a channel received an `ATTACHED` `ProtocolMessage`. (This is copied from ably-js, will document this method properly once exact meaning decided.)
 ///

Source/ARTJsonLikeEncoder.m

@@ -1102,6 +1102,16 @@ - (NSData *)encode:(id)obj error:(NSError **)error {
     return encoded;
 }
 
+/// Converts an `ARTEncoderFormat` to an `APEncodingFormat`.
+- (APEncodingFormat)apEncodingFormatFromARTEncoderFormat:(ARTEncoderFormat)format {
+    switch (format) {
+        case ARTEncoderFormatJson:
+            return APEncodingFormatJSON;
+        case ARTEncoderFormatMsgPack:
+            return APEncodingFormatMessagePack;
+    }
+}
+
 /// Uses the LiveObjects plugin to decode an array of `ObjectMessage`s.
 ///
 /// Returns `nil` if the LiveObjects plugin has not been supplied, or if we fail to decode any of the `ObjectMessage`s.
@@ -1134,9 +1144,11 @@ - (NSData *)encode:(id)obj error:(NSError **)error {
                                                                                          indexInParent:i];
 
         ARTErrorInfo *error;
+        APEncodingFormat format = [self apEncodingFormatFromARTEncoderFormat:[self format]];
 
         id<APObjectMessageProtocol> objectMessage = [liveObjectsPlugin decodeObjectMessage:item
                                                                                    context:decodingContext
+                                                                                    format:format
                                                                                      error:&error];
 
         if (!objectMessage) {
@@ -1167,9 +1179,10 @@ - (NSData *)encode:(id)obj error:(NSError **)error {
     }
 
     NSMutableArray<NSDictionary *> *result = [NSMutableArray array];
+    APEncodingFormat format = [self apEncodingFormatFromARTEncoderFormat:[self format]];
 
     for (id objectMessage in objectMessages) {
-        [result addObject:[liveObjectsPlugin encodeObjectMessage:objectMessage]];
+        [result addObject:[liveObjectsPlugin encodeObjectMessage:objectMessage format:format]];
     }
 
     return result;