TDesu.Telegram.Serialization
0.4.2
dotnet add package TDesu.Telegram.Serialization --version 0.4.2
NuGet\Install-Package TDesu.Telegram.Serialization -Version 0.4.2
<PackageReference Include="TDesu.Telegram.Serialization" Version="0.4.2" />
<PackageVersion Include="TDesu.Telegram.Serialization" Version="0.4.2" />
<PackageReference Include="TDesu.Telegram.Serialization" />
paket add TDesu.Telegram.Serialization --version 0.4.2
#r "nuget: TDesu.Telegram.Serialization, 0.4.2"
#:package TDesu.Telegram.Serialization@0.4.2
#addin nuget:?package=TDesu.Telegram.Serialization&version=0.4.2
#tool nuget:?package=TDesu.Telegram.Serialization&version=0.4.2
TDesu.Telegram.Serialization
Pure runtime primitives for Telegram's TL (Type Language) wire format: a pooled write buffer and a bounds-checked reader over byte[]. No reflection, no runtime codegen, no schema dependency.
The library is intentionally schema-agnostic. To get types for specific TL constructors,
run td-tl-gen against your own
schema + overrides TOML and commit the result into your own project.
0.4.0 (breaking) dropped
IDisposablefromTlReadBufferand removed thetl {}/tlPooled {}/tlInto {}computation expression,PooledBytes,DetachBuffer,StreamPositionandPatchInt32— none had a consumer, and the computation expression's own README examples did not compile. SeeRELEASE_NOTES.mdfor the full list and the migration.0.3.0 (breaking) removed the schema-pinned
Generated*.g.fsartifacts that 0.2.0 included as a transitional layer. SeeRELEASE_NOTES.mdfor that migration.
Install
dotnet add package TDesu.Telegram.Serialization
TlWriteBuffer
Pooled, resizable write buffer backed by ArrayPool<byte>. IDisposable —
returns the buffer to the pool on dispose.
open TDesu.Serialization
use w = new TlWriteBuffer()
w.WriteConstructorId(0x997275b5u) // boolTrue
w.WriteInt32(42)
w.WriteInt64(123L)
w.WriteString("hello")
w.WriteBytes([| 1uy; 2uy; 3uy |])
w.WriteBool(true)
w.WriteRawBytes([| 1uy; 2uy |]) // byte[] overload
w.WriteRawBytes(ReadOnlySpan<byte>(someBuffer, 4, 8)) // ReadOnlySpan<byte> overload — no copy
let bytes = w.ToArray() // copy out
let span = w.WrittenSpan // zero-copy read
Also: WriteInt128, WriteInt256, WriteDouble, WriteVector.
WriteBytes and WriteString raise ArgumentException for a length of 2<sup>24</sup> bytes or
more — the extended length header only has 24 bits, so anything at or past that boundary cannot
be encoded and is rejected rather than silently wrapped.
Tl.build / Tl.bytesOf
The three lines every generated Serialize call site was retyping — rent a TlWriteBuffer,
write into it, copy the result out, dispose it:
open TDesu.Serialization
let bytes = Tl.build (fun w ->
w.WriteInt32(42)
w.WriteString("hello"))
// For a generated type exposing `static member Serialize: TlWriteBuffer * ^T -> unit`:
let requestBytes = Tl.bytesOf someGeneratedRequest
bytesOf value is exactly build (fun w -> T.Serialize(w, value)) for value's own type T,
picked up via an SRTP constraint rather than an interface — generated TL types have no common
base to implement one against. One project counted 11 hand-written copies of this pattern plus a
private SRTP helper reproducing bytesOf before this existed.
TlReadBuffer
Stateful reader over a byte[], or a bounded view over part of one. Not IDisposable — it owns
no resource to release.
let reader = TlReadBuffer(bytes) // the whole array
let view = TlReadBuffer(bytes, 4, 16) // a bounds-checked view: bytes[4 .. 19]
let cid = reader.ReadConstructorId()
let value = reader.ReadInt32()
let name = reader.ReadString() // decodes straight from the span, no byte[] copy
let data = reader.ReadBytes()
reader.Position // 0-based within this reader's own view; range-checked on assignment
reader.Length // this view's logical length
reader.Remaining // bytes left to read in this view
reader.HasMore // Remaining > 0
reader.Skip(n)
Zero-copy helpers, for a caller that wants to forward or hash bytes rather than own a copy:
let span = reader.ReadSpan(16) // ReadOnlySpan<byte> over the next 16 bytes; no allocation
let inner = reader.Slice(32) // a second TlReadBuffer over the same array, next 32 bytes;
// advances `reader` past them
Peeking at the next constructor id without consuming it — for dispatching on a union's cid
before choosing which Deserialize to call:
let cid = reader.PeekConstructorId() // bounded: raises if fewer than 4 bytes remain
match reader.TryPeekConstructorId() with // ValueNone instead of raising
| ValueSome cid -> // enough bytes to decide
| ValueNone -> // not a full frame yet
Every read that finds the buffer too short, or an unrecognised bool/vector constructor id,
raises TlFormatException — one exception type for "this input is malformed," instead of the
ArgumentOutOfRangeException/IndexOutOfRangeException/InvalidOperationException mix earlier
versions raised depending which method you called. A bad argument to the reader's own API (a
negative Position, an out-of-range (data, offset, count)) is a separate concern and still
raises ArgumentException/ArgumentOutOfRangeException, because that is the caller misusing the
type rather than Telegram sending something malformed.
Vector header
TlWriters.writeVectorHeader is the only auxiliary helper. Use it when emitting
a TL Vector<T> payload by hand.
TlWriters.writeVectorHeader w 3 // writes 0x1cb5c415u + count(3)
for item in items do writeItem w item
TlConstants
The wire-format literals both buffers use — public since 0.4.0 so a consumer that needs the vector or bool constructor ids does not have to retype them:
TlConstants.BoolTrue // 0x997275b5u
TlConstants.BoolFalse // 0xbc799737u
TlConstants.VectorConstructorId // 0x1cb5c415u
TlConstants.MaxByteLength // 16777216 (2^24) — one past the largest length WriteBytes/WriteString can encode
Generating schema-aware types
This package deliberately does not bundle constructor IDs, request types, or
serializer DUs — those are project-specific (which constructors? which layer?
which dual-layer aliases? which undocumented extras?). Use
td-tl-gen to produce
them yourself:
dotnet tool install --global TDesu.Telegram.TL.Generator
td-tl-gen --schema cached/api.tl --mtproto-schema cached/mtproto.tl \
--output ./MyProject/Generated --namespace MyProject.Serialization \
--overrides my-overrides.toml \
--target cid types writers
Commit the generated .g.fs files into your project. They reference
TDesu.Serialization types from this package and recompile against any version.
Dependencies
- TDesu.FSharp (>= 2.0.0) —
Guardfor argument validation,Bytes/ArrayPoolfromTDesu.FSharp.Buffersfor the pooled-buffer plumbing. - No other dependencies
Building
dotnet build
dotnet test
License
| Product | Versions Compatible and additional computed target framework versions. |
|---|---|
| .NET | net5.0 was computed. net5.0-windows was computed. net6.0 was computed. net6.0-android was computed. net6.0-ios was computed. net6.0-maccatalyst was computed. net6.0-macos was computed. net6.0-tvos was computed. net6.0-windows was computed. net7.0 was computed. net7.0-android was computed. net7.0-ios was computed. net7.0-maccatalyst was computed. net7.0-macos was computed. net7.0-tvos was computed. net7.0-windows was computed. net8.0 was computed. net8.0-android was computed. net8.0-browser was computed. net8.0-ios was computed. net8.0-maccatalyst was computed. net8.0-macos was computed. net8.0-tvos was computed. net8.0-windows was computed. net9.0 was computed. net9.0-android was computed. net9.0-browser was computed. net9.0-ios was computed. net9.0-maccatalyst was computed. net9.0-macos was computed. net9.0-tvos was computed. net9.0-windows was computed. net10.0 was computed. net10.0-android was computed. net10.0-browser was computed. net10.0-ios was computed. net10.0-maccatalyst was computed. net10.0-macos was computed. net10.0-tvos was computed. net10.0-windows was computed. |
| .NET Core | netcoreapp3.0 was computed. netcoreapp3.1 was computed. |
| .NET Standard | netstandard2.1 is compatible. |
| MonoAndroid | monoandroid was computed. |
| MonoMac | monomac was computed. |
| MonoTouch | monotouch was computed. |
| Tizen | tizen60 was computed. |
| Xamarin.iOS | xamarinios was computed. |
| Xamarin.Mac | xamarinmac was computed. |
| Xamarin.TVOS | xamarintvos was computed. |
| Xamarin.WatchOS | xamarinwatchos was computed. |
-
.NETStandard 2.1
- TDesu.FSharp (>= 2.0.0)
NuGet packages (2)
Showing the top 2 NuGet packages that depend on TDesu.Telegram.Serialization:
| Package | Downloads |
|---|---|
|
TDesu.Telegram.Transport
MTProto TCP/intermediate transport — frame codec + TCP socket adapter. Used by clients to talk to MTProto endpoints. |
|
|
TDesu.Telegram.Protocol
MTProto protocol core — encrypted/unencrypted message framing, session state, auth key Diffie–Hellman exchange, RPC dispatcher, and high-level client. Builds on TDesu.Telegram.Transport for TCP and TDesu.Telegram.Crypto for AES/RSA. |
GitHub repositories
This package is not used by any popular GitHub repositories.