mtproto 0.0.13 → 0.0.14

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ef5c11c5bf0b9bfe4f3b80e905270264b5658bc55a2932e92c945df8ba0dc723
-  data.tar.gz: 58fec06d053d66b52c382049e7fb917dbf0c4af2395c7f81f5dcb66d70778228
+  metadata.gz: e4d643a3e49ecb3e3d2744952aa42edb40237c2307a0d7d316c1ed350443bab7
+  data.tar.gz: f3f21cb5f49140c69d1d8dd8d34b7b12f2cf0aaaae48efedc9bce6b954cdf1ae
 SHA512:
-  metadata.gz: b108736ec52172e501b8609b6c8b5596052b7fa80d72bfaa6cadb393baddbe89ec009148da487f3b8c16b9a6000e5bdea4aa5b15c77fd9ddd19ce43ae8db6763
-  data.tar.gz: 3268f1b6943ea7c470ee274a56cbc3e4d3c5a2aebff7e8b5b4522805e8a922756932cb396909650f520cb3153d75d8e34a61e5952916602421ed01df2b9e5c7e
+  metadata.gz: ba8f0adc18f691fa85b9722dc994ac1784a30d9465f972f9992da6a95027722655467952c94b31877531c08fb5fa45effef9fc77558ff6b7e2a8cccc69d9310e
+  data.tar.gz: a95133f8932df90e61b39de4cd6342b6d5f5b790bd803eacb3cde964b6d2fbd1e6983fc6f2bfb0543c25568287225e094f10e95bdc52a68fbbc5ff9ebbdc8484

data/FUTURE.md

@@ -0,0 +1,9 @@
+# Future Tasks
+
+## Implement msgs_ack
+
+Client should acknowledge received messages by sending `msgs_ack` with a list of received
+msg_ids. Without this, the server may redeliver messages it considers unacknowledged.
+
+Also add handling for `bad_msg_notification` responses from the server (constructor exists
+in constructors.rb but no handler in Client#process_message).

data/docs/test_architecture_level1.md

@@ -0,0 +1,237 @@
+# Level 1 Test Architecture: Constructor Capture and Test Cases
+
+## Purpose
+
+Collect real data from Telegram in specific user-facing scenarios and use it as the
+source for two things:
+
+1. **A library of TL constructor variants**: every concrete form of every constructor
+   we ever observe (across all the optional fields and flag-driven shapes) — stored
+   under `spec/fixtures/level1/constructors/`. This is the format catalog Level 2
+   (deserialization) and Level 3 (API logic) tests work against.
+2. **Test cases**: one user-facing scenario per executable script under `spec/level1/`,
+   producing a folder of fixtures under `spec/fixtures/level1/test_cases/<scenario>/`.
+   A test case captures whatever Telegram actually sends end-to-end during that
+   scenario.
+
+The set of test cases is chosen so that, taken together, they cover every variant
+of every constructor we need to characterize — not so that they reproduce every
+possible user-facing scenario. The same constructor can show up in many test cases
+and inside different parent constructors; we only need to see each variant at least
+once.
+
+## How It Works
+
+These are semi-manual tests. Each test case:
+
+1. Connects to Telegram with a pre-authenticated session
+2. Tells the user what to do (e.g., "Send a text message to this account")
+3. Waits until the corresponding data arrives from Telegram
+4. Saves the raw decrypted message bodies as `.bin` files and a `captured.json`
+   listing the TL constructors received
+
+On subsequent runs, the freshly captured constructor list is compared to the
+previously stored `captured.json` for the same test case. If they differ, the
+script prints a `CHANGED` warning — usually a signal that Telegram's wire-level
+behavior shifted and the fixtures need to be re-examined.
+
+## Example Scenarios
+
+The list below illustrates the kinds of situations these tests cover.
+It is not exhaustive — new scenarios are added as needed.
+
+- Text message in private chat
+- Text message in a group
+- Text message in a channel
+- Reply to a message
+- Forwarded message
+- Message with photo
+- Message with document
+- Message in a forum topic
+- User joined a group
+- User left a group
+- Message edited
+- Message deleted
+
+## Fixture Layout
+
+```
+spec/fixtures/level1/
+  test_cases/
+    receive_private_text_message/
+      001.bin
+      002.bin
+      003.bin
+      004.bin
+      captured.json
+    receive_group_text_message/
+      001.bin
+      002.bin
+      captured.json
+    ...
+  constructors/
+    updateShortMessage/
+      plain_in.bin
+      with_fwd_from.bin
+      with_reply_to.bin
+      with_entities_bold.bin
+      ...
+    messageFwdHeader/
+      from_user.bin
+      from_channel.bin
+      ...
+    messageEntity/
+      bold.bin
+      italic.bin
+      url.bin
+      ...
+    ...
+```
+
+Each test case produces:
+
+- One or more `.bin` files with raw decrypted message bodies, numbered sequentially
+  in arrival order (one user action may trigger multiple messages from Telegram).
+- A `captured.json` listing each captured message as an object with two fields —
+  the TL `constructor` name and the `file` containing its raw body bytes.
+
+Shape of `captured.json`:
+
+```json
+[
+  { "constructor": "msgs_ack",           "file": "001.bin" },
+  { "constructor": "updateShort",        "file": "002.bin" },
+  { "constructor": "updateShortMessage", "file": "003.bin" }
+]
+```
+
+The `constructors/` tree is a separate, deduplicated library populated from
+test-case captures: one `.bin` per distinct variant of each constructor, with
+the filename describing the variant (e.g. `plain_in.bin`, `with_fwd_from.bin`).
+No metadata file — the folder + filename are the catalogue.
+
+## File Structure
+
+Each scenario is an executable script (not an RSpec spec). The flow is
+interactive — the script prints instructions, waits on STDIN, then captures
+the resulting Telegram traffic. RSpec's declarative `describe`/`it` shape
+doesn't fit that, so these scripts live under `spec/level1/` alongside the
+rspec tree but are invoked directly, not through `rake spec`.
+
+```
+spec/
+  level1/
+    support/                       # Shared test infrastructure
+    receive_private_text_message   # Executable script (one per test case)
+    receive_group_text_message
+    ...
+  fixtures/
+    level1/
+      test_cases/                  # Per-test-case captures (folder per scenario)
+      constructors/                # Deduplicated constructor variant library
+```
+
+## Running with xp
+
+These scripts are interactive — they print a prompt, block on STDIN, run
+until the captured traffic arrives, then exit. When the operator is a
+Claude Code bot driving the repo from short-lived Bash invocations, a
+plain shell can't keep the script alive across calls: each tool call is
+a fresh process, so the script would exit (or be killed) the moment the
+shell returns.
+
+The way around it is [xp](https://github.com/alev-pro/xp) — a small
+process stdin/stdout multiplexer. A long-lived xp daemon owns the
+script under a named topic; separate client invocations send to its
+stdin and read from its stdout. The script keeps running between
+calls.
+
+The recipe below assumes xp is built at
+`~/devel/alev-pro/xp/target/release/xp`. Adjust the path if it lives
+elsewhere.
+
+### 1. Start the xp daemon
+
+```sh
+nohup ~/devel/alev-pro/xp/target/release/xp --run-daemon \
+  >/tmp/xp-daemon.log 2>&1 &
+echo $! > /tmp/xp-daemon.pid
+```
+
+The daemon binds a Unix socket at `/tmp/xp-<uid>.sock`. The PID file
+is just a convention so teardown can `kill` by PID — `pkill -f` on
+the daemon command line is dangerous because it can also match the
+caller's own wrapper shell.
+
+### 2. Spawn the Level 1 script under a topic
+
+```sh
+~/devel/alev-pro/xp/target/release/xp -t l1 -- \
+  bash -lc 'cd ~/devel/alev-pro/mtproto-ruby \
+            && bundle exec spec/level1/receive_private_text_message'
+```
+
+`l1` is just a chosen topic name. Any string works.
+
+### 3. Read the script's stdout
+
+```sh
+~/devel/alev-pro/xp/target/release/xp -t l1 --read-stdout --cursor c1
+```
+
+`--cursor c1` keeps a stable read position across separate xp client
+invocations. Without `--cursor`, xp keys the cursor on the caller's
+posix session id (`getsid(0)`), and every fresh Bash tool call has a
+new sid — meaning every read replays the buffer from byte 0.
+
+Expected initial output:
+
+```
+Connecting...
+Connected as: <first> <last>
+Send a text message to this account in a private chat.
+Press Enter when done.
+```
+
+### 4. Trigger the scenario
+
+Perform the user-facing action the script asks for (in this case,
+send a private text message to the test-DC account from another
+Telegram client).
+
+### 5. Unblock the script
+
+```sh
+echo "" | ~/devel/alev-pro/xp/target/release/xp -t l1 --put-to-stdin
+```
+
+The script then prints the captured constructor list and writes the
+fixtures + `captured.json` to `spec/fixtures/level1/test_cases/<scenario>/`.
+
+### 6. Tear down
+
+```sh
+kill "$(cat /tmp/xp-daemon.pid)"
+rm -f /tmp/xp-<uid>.sock /tmp/xp-daemon.pid
+```
+
+### STDOUT buffering caveat
+
+Ruby's `STDOUT` defaults to full buffering when stdout is not a tty,
+and xp pipes the child's stdout through a plain pipe rather than a
+pty. Without an explicit flush the script's `puts` calls would stay
+in-process until exit, and step 3 would read nothing. Each Level 1
+script must therefore set `STDOUT.sync = true` near the top, before
+any output.
+
+### `bash -lc` noise
+
+When `bash -i` runs under xp without a pty, it complains:
+
+```
+bash: cannot set terminal process group (...): Inappropriate ioctl for device
+bash: no job control in this shell
+```
+
+That noise lands on stderr, which the daemon inherits and writes into
+`/tmp/xp-daemon.log`. The script's own stdout stays clean.

data/lib/mtproto/auth_key_generator.rb

@@ -86,13 +86,13 @@ module MTProto
     private
 
     def send_and_receive(rpc, response_class)
-      message = Message.new(rpc.body)
+      message = Message.new(rpc.serialize)
       @connection.send(Transport::Packet.new(message.bytes))
 
       response_packet = @connection.receive
       raise 'Receive timeout' if response_packet.nil?
 
-      result = response_class.parse(Message.parse(response_packet))
+      result = response_class.deserialize(Message.parse(response_packet))
 
       raise 'Nonce mismatch!' if rpc.respond_to?(:nonce) && result.nonce != rpc.nonce
       raise 'Server nonce mismatch!' if rpc.respond_to?(:server_nonce) && result.server_nonce != rpc.server_nonce
@@ -114,7 +114,7 @@ module MTProto
         new_nonce: new_nonce,
         dc: dc_value
       )
-      encrypted_data = Crypto::RSA_PAD.encrypt(inner_data.body.pack('C*'), server_key)
+      encrypted_data = Crypto::RSA_PAD.encrypt(inner_data.serialize.pack('C*'), server_key)
 
       rpc = TL::ReqDHParams.new(
         nonce: res_pq.nonce,
@@ -149,7 +149,7 @@ module MTProto
         answer = answer[0..-2]
       end
 
-      TL::ServerDHInnerData.parse(answer)
+      TL::ServerDHInnerData.deserialize(answer)
     end
 
     def send_client_dh_params(res_pq, _new_nonce, client_dh_params, tmp_aes_key, tmp_aes_iv)
@@ -160,7 +160,7 @@ module MTProto
         g_b: client_dh_params[:g_b_bytes]
       )
 
-      client_dh_data = client_dh_inner_data.body.pack('C*')
+      client_dh_data = client_dh_inner_data.serialize.pack('C*')
       client_dh_data_with_hash = Digest::SHA1.digest(client_dh_data) + client_dh_data
 
       padding_length = (16 - (client_dh_data_with_hash.bytesize % 16)) % 16

data/lib/mtproto/client/api/get_contacts.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+require_relative '../../tl/objects/get_contacts'
+require_relative '../../tl/objects/contacts'
+
+module MTProto
+  class Client
+    class API
+      def get_contacts(hash: 0)
+        rpc_call(TL::GetContacts.new(hash: hash), TL::Contacts).body
+      end
+    end
+  end
+end

data/lib/mtproto/client/api/send_message.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+require_relative '../../tl/objects/send_message'
+require_relative '../../tl/objects/update_short_sent_message'
+
+module MTProto
+  class Client
+    class API
+      def send_message(peer:, message:, random_id: nil)
+        rpc_call(TL::SendMessage.new(peer: peer, message: message, random_id: random_id),
+                 TL::UpdateShortSentMessage).body
+      end
+    end
+  end
+end

data/lib/mtproto/client/api.rb

@@ -10,6 +10,8 @@ require_relative 'api/get_dialogs'
 require_relative 'api/get_history'
 require_relative 'api/get_updates_state'
 require_relative 'api/get_updates_difference'
+require_relative 'api/send_message'
+require_relative 'api/get_contacts'
 
 module MTProto
   class Client

data/lib/mtproto/client/rpc/response.rb

@@ -43,7 +43,7 @@ module MTProto
         end
 
         def signal(raw_body)
-          @result = @response_class.parse(raw_body)
+          @result = @response_class.deserialize(raw_body)
           @condition.signal
         end
 

data/lib/mtproto/client/rpc.rb

@@ -69,8 +69,8 @@ module MTProto
       private
 
       def serialize_request(request)
-        if request.respond_to?(:body)
-          request.body.pack('C*')
+        if request.respond_to?(:serialize)
+          request.serialize.pack('C*')
         else
           request
         end

data/lib/mtproto/client.rb

@@ -92,24 +92,7 @@ module MTProto
 
       begin
         Async do
-          @running = true
-          @receiver_task = Async do
-            @connection.receive do |packet, error|
-              if error
-                warn "[MTProto] Packet read error: #{error.message}"
-                next
-              end
-
-              decrypted = EncryptedMessage.decrypt(
-                auth_key: @auth_key,
-                encrypted_message_data: packet.data.pack('C*'),
-                sender: :server
-              )
-
-              process_message(decrypted[:body])
-            end
-          end
-
+          start_receiving!
           yield self
         ensure
           disconnect!
@@ -119,6 +102,33 @@ module MTProto
       end
     end
 
+    # Start the receiver task without taking over the current Async reactor.
+    # Use when orchestrating multiple clients in a shared Async block — call
+    # from inside an Async do ... end. The caller is responsible for
+    # disconnect! at the end.
+    def start_receiving!
+      raise 'Auth key not set' unless auth_key?
+      raise 'Mainloop already running' if @running
+
+      @running = true
+      @receiver_task = Async do
+        @connection.receive do |packet, error|
+          if error
+            warn "[MTProto] Packet read error: #{error.message}"
+            next
+          end
+
+          decrypted = EncryptedMessage.decrypt(
+            auth_key: @auth_key,
+            encrypted_message_data: packet.data.pack('C*'),
+            sender: :server
+          )
+
+          process_message(decrypted[:body])
+        end
+      end
+    end
+
     def disconnect!
       @running = false
       @receiver_task&.stop

data/lib/mtproto/tl/constructors.rb

@@ -19,6 +19,7 @@ module MTProto
       PEER_CHAT = 0x36c6019a
       PEER_CHANNEL = 0xa2a5371e
       INPUT_PEER_EMPTY = 0x7f3b18ea
+      INPUT_PEER_SELF = 0x7da07ec9
       INPUT_PEER_USER = 0xdde8a54c
       INPUT_PEER_CHAT = 0x35a95cb9
       INPUT_PEER_CHANNEL = 0x27bcbbfc
@@ -71,9 +72,24 @@ module MTProto
       USERS_GET_USERS = 0x0d91a548
       USER = 0x020b1422
 
+      # Contacts
+      CONTACTS_GET_CONTACTS = 0x5dd69e12
+      CONTACTS_CONTACTS = 0xeae87e42
+      CONTACTS_CONTACTS_NOT_MODIFIED = 0xb74ba9d2
+      CONTACT = 0x145ade0b
+
       # Messages
       MESSAGES_GET_DIALOGS = 0xa0f4cb4f
       MESSAGES_GET_HISTORY = 0x4423e6c5
+      MESSAGES_SEND_MESSAGE = 0xfe05dc9a
+      MESSAGES_SEND_MEDIA = 0xac55d9c1
+      MESSAGES_EDIT_MESSAGE = 0xdfd14005
+      MESSAGES_DELETE_MESSAGES = 0xe58e95d2
+
+      # Upload + media
+      UPLOAD_SAVE_FILE_PART = 0xb304a621
+      INPUT_FILE = 0xf52ff27f
+      INPUT_MEDIA_UPLOADED_PHOTO = 0x1e287d04
       MESSAGES_DIALOGS = 0x15ba6c40
       MESSAGES_DIALOGS_SLICE = 0x71e094f3
       MESSAGE = 0x9815cec8
@@ -87,6 +103,16 @@ module MTProto
       UPDATE_NEW_MESSAGE = 0x1f2b0afd
       UPDATE_SHORT = 0x78d4dec1
       UPDATE_SHORT_MESSAGE = 0x313bc7f8
+      UPDATE_SHORT_SENT_MESSAGE = 0x9015e101
+
+      # Channel updates
+      INPUT_CHANNEL = 0xf35aec28
+      INPUT_CHANNEL_EMPTY = 0xee8c1e86
+      CHANNEL_MESSAGES_FILTER_EMPTY = 0x94d42ee7
+      UPDATES_GET_CHANNEL_DIFFERENCE = 0x03173d78
+      UPDATES_CHANNEL_DIFFERENCE = 0x2064674e
+      UPDATES_CHANNEL_DIFFERENCE_EMPTY = 0x3e11affb
+      UPDATES_CHANNEL_DIFFERENCE_TOO_LONG = 0xa4bcc6fe
       UPDATES_GET_STATE = 0xedd4882a
       UPDATES_STATE = 0xa56c2a3e
       UPDATES_GET_DIFFERENCE = 0x19c2f763

data/lib/mtproto/tl/object.rb

@@ -12,7 +12,7 @@ module MTProto
         @payload = payload
       end
 
-      def self.parse(message)
+      def self.deserialize(message)
         body = message.body
         constructor_id = b_u32(body[0, 4])
         constructor = ConstructorNames::NAMES.fetch(constructor_id)

data/lib/mtproto/tl/objects/account_password.rb

@@ -12,7 +12,7 @@ module MTProto
         @srp_id = srp_id
       end
 
-      def self.parse(data)
+      def self.deserialize(data)
         constructor = data[0, 4].unpack1('L<')
         raise UnexpectedConstructorError, constructor unless constructor == Constructors::ACCOUNT_PASSWORD
 

data/lib/mtproto/tl/objects/authorization.rb

@@ -16,7 +16,7 @@ module MTProto
         !@sign_up_required && @user_id
       end
 
-      def self.parse(data)
+      def self.deserialize(data)
         constructor = data[0, 4].unpack1('L<')
 
         return new(sign_up_required: true) if constructor == Constructors::AUTH_AUTHORIZATION_SIGN_UP_REQUIRED

data/lib/mtproto/tl/objects/channels_create_channel.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module MTProto
+  module TL
+    # channels.createChannel — create a broadcast channel or, with the megagroup
+    # flag, a supergroup. Returns Updates carrying the new channel.
+    class ChannelsCreateChannel
+      include Binary
+
+      CONSTRUCTOR = 0x91006707
+
+      def initialize(title:, about: '', megagroup: true, broadcast: false)
+        @title = title
+        @about = about
+        @megagroup = megagroup
+        @broadcast = broadcast
+      end
+
+      def serialize
+        flags = 0
+        flags |= (1 << 0) if @broadcast
+        flags |= (1 << 1) if @megagroup
+
+        result = u32_b(CONSTRUCTOR)
+        result += u32_b(flags)
+        result += serialize_tl_string(@title)
+        result += serialize_tl_string(@about)
+        result
+      end
+
+      private
+
+      def serialize_tl_string(str)
+        bytes = str.to_s.b.bytes
+        length = bytes.length
+        if length <= 253
+          [length] + bytes + padding(length + 1)
+        else
+          [254] + u32_b(length)[0, 3] + bytes + padding(length + 4)
+        end
+      end
+
+      def padding(current_length)
+        [0] * ((4 - (current_length % 4)) % 4)
+      end
+    end
+  end
+end

data/lib/mtproto/tl/objects/channels_delete_messages.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module MTProto
+  module TL
+    class ChannelsDeleteMessages
+      include Binary
+
+      CONSTRUCTOR = 0x84c1fd4e
+
+      def initialize(channel:, ids:)
+        @channel = channel
+        @ids = ids
+      end
+
+      def serialize
+        result = u32_b(CONSTRUCTOR)
+        result += serialize_input_channel
+        result += u32_b(Constructors::VECTOR) + u32_b(@ids.length)
+        @ids.each { |id| result += u32_b(id) }
+        result
+      end
+
+      private
+
+      def serialize_input_channel
+        u32_b(Constructors::INPUT_CHANNEL) +
+          u64_b(@channel[:id]) +
+          u64_b(@channel[:access_hash])
+      end
+    end
+  end
+end

data/lib/mtproto/tl/objects/channels_delete_participant_history.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module MTProto
+  module TL
+    class ChannelsDeleteParticipantHistory
+      include Binary
+
+      CONSTRUCTOR = 0x367544db
+
+      def initialize(channel:, participant:)
+        @channel = channel
+        @participant = participant
+      end
+
+      def serialize
+        result = u32_b(CONSTRUCTOR)
+        result += u32_b(Constructors::INPUT_CHANNEL) + u64_b(@channel[:id]) + u64_b(@channel[:access_hash])
+        result += serialize_input_peer(@participant)
+        result
+      end
+
+      private
+
+      def serialize_input_peer(peer)
+        case peer[:type]
+        when :user
+          u32_b(Constructors::INPUT_PEER_USER) + u64_b(peer[:id]) + u64_b(peer[:access_hash] || 0)
+        else
+          raise "Unsupported participant peer type: #{peer[:type]}"
+        end
+      end
+    end
+  end
+end

data/lib/mtproto/tl/objects/channels_edit_banned.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module MTProto
+  module TL
+    class ChannelsEditBanned
+      include Binary
+
+      CONSTRUCTOR = 0x96e6cd81
+      CHAT_BANNED_RIGHTS = 0x9f120418
+
+      def initialize(channel:, participant:, view_messages: false, send_messages: false, until_date: 0)
+        @channel = channel
+        @participant = participant
+        @view_messages = view_messages
+        @send_messages = send_messages
+        @until_date = until_date
+      end
+
+      def serialize
+        result = u32_b(CONSTRUCTOR)
+        result += serialize_input_channel
+        result += serialize_input_peer(@participant)
+        result += serialize_banned_rights
+        result
+      end
+
+      private
+
+      def serialize_banned_rights
+        flags = 0
+        flags |= (1 << 0) if @view_messages
+        flags |= (1 << 1) if @send_messages
+        u32_b(CHAT_BANNED_RIGHTS) + u32_b(flags) + u32_b(@until_date)
+      end
+
+      def serialize_input_channel
+        u32_b(Constructors::INPUT_CHANNEL) +
+          u64_b(@channel[:id]) +
+          u64_b(@channel[:access_hash])
+      end
+
+      def serialize_input_peer(peer)
+        case peer[:type]
+        when :user
+          u32_b(Constructors::INPUT_PEER_USER) + u64_b(peer[:id]) + u64_b(peer[:access_hash] || 0)
+        when :channel
+          u32_b(Constructors::INPUT_PEER_CHANNEL) + u64_b(peer[:id]) + u64_b(peer[:access_hash] || 0)
+        else
+          raise "Unsupported participant peer type: #{peer[:type]}"
+        end
+      end
+    end
+  end
+end