Skip to content

Latest commit

 

History

History
79 lines (63 loc) · 5.08 KB

UPGRADING.md

File metadata and controls

79 lines (63 loc) · 5.08 KB

How to upgrade to a newer layer

Context

CatraProto provides a simplified API for some Telegram features. This simplified API (eg. File Handling) needs to be maintained and to be updated when necessary to keep everything working correctly. The CatraProto.TL.Generator (which requires some refactoring, so PRs are welcome) provides some tools to easily track changes across the entire schema and help make the right adjustments:

  • schema.tl is where all TL schemas are defined, including the ones internally used by CatraProto.
  • knownContexts.json is a JSON-encoded list of all constructors (together with their IDs, to easily check if the constructor changed) that contain either a Document, a Photo object or another TL-Object which eventually links to one of the first two.
  • watchFor.catraWatch is a hand-written file used to manually get notified if one or more of the constructors specified have changed.

All of these checks run automatically when generating TL related code.

What to do when changes are detected in knownContexts.json

When a new constructor bringing to a Photo or Document object (file object, from now on) it's of vital importance to update the code that handles contexts. When adding a new context it is not necessary to update the FileIdVersion, older versions of CatraProto are supposed to return an error if they don't recognize a context. Instead, the version is supposed to be incremented when a breaking change to the serialization is scheme is made.

The current FileId scheme looks like this:

| version (u16) | type (u16) | id (i64) | access_hash (i64) | dc_id (i32) | size (i64) | static_sizes (i32 + PhotoSize objects) | video_sizes (i32 + VideoSize objects) | file_reference (bytes) | context (Context object) |

The current UniqueId scheme looks like this:

| version (u16) | type (u16) | id (i64) | dc_id (i32) |

When new or different contexts are detected a new context object in schema.tl must be created. If a context object must be changed a new one has to be created with the same name as the old one but with a version number at the end. It is also useful (but not mandatory, unless it's not clear what has changed) to add a comment describing the difference from the previous version.

Old Context:

contextFromMessage#e11a9fd9 peer:long msg_id:int = Context;

New Context:

// This context is different from contextFromMessage previous for the following reasons:
// - A new pikachu parameter was added by Telegram to each message, and it is required to use getMessages.
// - The peer parameter now only accepts values divisible by 2
contextFromMessageV2#e11a9fd9 peer:long msg_id:int pikachu:int = Context;

Just like the TL schema provided by Telegram, the constructor ID must be generated by computing the CRC32 value of the objects except the semicolon and the ID.

// used to generate ID
contextFromMessageV2 peer:long msg_id:int pikachu:int = Context

// written in schema.tl
contextFromMessageV2#e11a9fd9 peer:long msg_id:int pikachu:int = Context;

The old context must not be removed from the schema.tl file. Obviously, the code in FileLocation.cs must also be changed in order to accomodate these changes.

What to do when changes are detected in watchFor.catrawatch

- photoSize and/or videoSize have changed:

In this case, it is important to create new objects in order not to lose backwards compatibility. The object must meet the following requirements:

  • It must have the same name as the previous object, except it must end with "OldX" where X is an increasing number starting from 1.
  • It must be locate under the CatraProto.Client.TL.Schemas.Sizes in the schema.tl file.
  • The constructor ID must be the same as the old object. If the new Id is 1234, and the old one is 3212, this object we're creating must have Id 3212.

Obviously, the code must be updated to convert (while deserializing) the old object to the newest one.

- inputMediaUploadedDocument and/or inputMediaUploadedPhoto have changed:

In this case, the classes UploadMetadataDocument and UploadMetadataPhoto must accomodate the changes made by Telegram.

Move the new objects to the right directories

To bring to life the changes we've written in schema.tl you must follow these steps:

  • Navigate to src/CatraProto.Client/TL/Requests
  • Delete everything except the Overrides folder
  • Navigate to src/CatraProto.Client/TL/Schemas
  • Delete everything except the Overrides folder and MergedProviderDefaults.cs
  • Delete src/CatraProto.Client/Updates/UpdateTools.cs
  • Navigate to src/CatraProto.TL.Generator/bin/Build_Config/dotnet_version/
  • Delete the CatraProto folder
  • Run the code generator
  • Copy the contents of CatraProto/Client\TL to src/CatraProto.Client/TL/
  • Copy CatraProto/Client/Updates/UpdateTools.Autogen.cs to src/CatraProto.Client/Updates/

Final remarks

It's also important to update this document when necessary. PRs are welcome but they must meet all requirements.