#813 Version handling

src/Azos.Sky.Server/Fabric/Server/FiberMemory.cs

@@ -49,6 +49,10 @@ public sealed class FiberMemory
     public FiberMemory(BixReader reader)
     {
       m_Version     = reader.ReadInt();
+
+      (m_Version <= Constraints.MEMORY_FORMAT_VERSION).IsTrue("Wire Version <= MEMORY_FORMAT_VERSION");
+
+
       m_Status      = (MemoryStatus)reader.ReadByte();
 
       m_Id          = new FiberId(reader.ReadAtom(),
@@ -63,13 +67,16 @@ public FiberMemory(BixReader reader)
     }
 
     /// <summary>
+    /// Processor &lt;=== Shard<br/>
     /// Called by memory shard: writes binary representation of this class one-way that is:
     /// it can only be read back by <see cref="FiberMemory(BixReader)"/>.
     /// The changes to memory are NOT communicated back using this method, instead <see cref="FiberMemoryDelta"/> is used
     /// </summary>
-    public void WriteOneWay(BixWriter writer)
+    public void WriteOneWay(BixWriter writer, int formatVersion)
     {
-      writer.Write(m_Version);
+      (formatVersion <= Constraints.MEMORY_FORMAT_VERSION).IsTrue("Wire Version <= MEMORY_FORMAT_VERSION");
+      writer.Write(formatVersion);
+
       writer.Write((byte)m_Status);
 
       writer.Write(m_Id.Runspace);
@@ -157,12 +164,17 @@ public FiberMemoryDelta MakeDeltaSnapshot(FiberStep? nextStep, FiberState curren
       return  result;
     }
 
+    /// <summary>
+    /// Materializes raw buffer into <see cref="FiberParameters"/> and <see cref="FiberState"/> of the specified types.
+    /// You can use <see cref="Version"/> to perform backward-compatible upgrades of serialization methods
+    /// </summary>
     public (FiberParameters pars, FiberState state) Unpack(Type tParameters, Type tState)
     {
       using var ms = new MemoryStream(m_Buffer);
 
       var pars = (FiberParameters)Serialization.SerializationUtils.MakeNewObjectInstance(tParameters);
-      //todo: Replace with Bix in future
+
+      //todo: Replace with Bix in future, use Version to conditional call one or another
       var map = JsonReader.DeserializeDataObject(ms) as JsonDataMap;
       JsonReader.ToDoc(pars, map, fromUI: false, JsonReader.DocReadOptions.BindByCode);
 

src/Azos.Sky.Server/Fabric/Server/FiberMemoryDelta.cs

@@ -28,6 +28,10 @@ internal FiberMemoryDelta(){ }
     public FiberMemoryDelta(BixReader reader)
     {
       Version = reader.ReadInt();
+
+      (Version <= Constraints.MEMORY_FORMAT_VERSION).IsTrue("Wire Version <= MEMORY_FORMAT_VERSION");
+
+
       Id = new FiberId(reader.ReadAtom(),
                        reader.ReadAtom(),
                        reader.ReadGDID());
@@ -63,13 +67,15 @@ public FiberMemoryDelta(BixReader reader)
     }
 
     /// <summary>
-    /// Called by memory shard: writes binary representation of this class one-way that is:
-    /// it can only be read back by <see cref="FiberMemory(BixReader)"/>.
-    /// The changes to memory are NOT communicated back using this method, instead <see cref="FiberMemoryDelta"/> is used
+    /// Processor ===&gt; Shard<br/>
+    /// Called by processor: writes binary representation of this class one-way that is:
+    /// it can only be read back by <see cref="FiberMemoryDelta(BixReader)"/>.
+    /// The changes to memory are NOT communicated back using this method, instead <see cref="FiberMemory"/> is used
     /// </summary>
-    public void WriteOneWay(BixWriter writer)
+    public void WriteOneWay(BixWriter writer, int formatVersion)
     {
-      writer.Write(Version);
+      (formatVersion <= Constraints.MEMORY_FORMAT_VERSION).IsTrue("Wire Version <= MEMORY_FORMAT_VERSION");
+      writer.Write(formatVersion);
 
       writer.Write(Id.Runspace);
       writer.Write(Id.MemoryShard);

src/Azos.Sky/Fabric/Constraints.cs

@@ -10,6 +10,13 @@ namespace Azos.Sky.Fabric
 {
   public static class Constraints
   {
+    /// <summary>
+    /// Memory format version describes the methods/protocols/serializers used to pack/unpack
+    /// memory representations into/from byte[].
+    /// Writers take version  parameter to write out in specific format.
+    /// Readers read the first version tag and then change their reading strategy as of that version
+    /// Assumption: versions are always backward-compatible, e.g. a written version 9 can be processed by reader version 9 or higher, but not lower than 9.
+    /// </summary>
     public const int MEMORY_FORMAT_VERSION = 1;
 
     public const int MAX_TAG_COUNT = 32;