Ayugram Custom Features
Overview
This doc owns TMessagesProj/src/main/java/com/radolyn/ayugram/** and the AyuGram string resources in TMessagesProj/…/ayu.xml. The package is a set of AyuGram-specific hooks and UI surfaces layered onto Telegram's controllers, storage, networking, and message cells. Most runtime entry points are static helpers that patched Telegram code can call: AyuConfig.java for feature flags, AyuMessagesController.java for deleted/edit-history persistence, AyuForwarder.java and easy/AyuEasyUtils.java for forwarding/resending restricted messages, sync/AyuSyncController.java for device sync, and utils/AyuGhostUtils.java/utils/AyuState.java for ghost-mode read-state routing.
Configuration is global, process-local state loaded from the ayuconfig SharedPreferences file in AyuConfig.java. loadConfig() initializes booleans for ghost mode, message saving, regex filtering, drawer buttons, AyuSync, and WAL mode; the preference screens mutate the same static fields and immediately persist via AyuConfig.editor. String-valued settings such as deletedMarkText, editedMarkText, syncServerURL, syncServerToken, and regexFilters are read lazily from preferences. Regex filters are stored as a JSON array string and compiled/cached by AyuFilter.java, with RegexFilterEditActivity.java validating new patterns before AyuConfig.addFilter() or editFilter() rebuilds the cache.
The main settings surface is ui/…/AyuGramPreferencesActivity.java, backed by strings in values*/ayu.xml. It exposes ghost essentials, deleted/edit history, message-saving preferences, QoL toggles, customization text, AyuSync status, and debug database actions. Subscreens include MessageSavingPreferencesActivity.java for media/formatting/reaction/bot save policy, RegexFiltersPreferencesActivity.java plus RegexFilterPopup.java/RegexFilterEditActivity.java for filter management, and AyuSyncPreferencesActivity.java for server URL, token, secure transport, profile, force-sync, and sync diagnostics. ui/…/AyuUi.java centralizes edit dialogs that persist string settings.
Message history state is stored in a Room database named ayu-data. database/AyuDatabase.java defines version 21 with EditedMessage, DeletedMessage, and DeletedMessageReaction; database/AyuData.java builds it with allowMainThreadQueries() and fallbackToDestructiveMigration(). database/…/AyuMessageBase.java is the shared persistence schema for user/dialog/topic/message identity, forwarding/reply metadata, text, serialized entities, media paths, thumbs, document type, document serialization, attributes, and MIME type. EditedMessageDao.java retrieves revisions and sync pages; DeletedMessageDao.java retrieves individual/ranged/grouped deleted messages, inserts deletion rows/reactions, checks existence, and deletes rows.
messages/AyuMessagesController.java is the persistence facade. It writes copied media under Downloads/AyuGram/Saved Attachments, uses the proprietary mapper com.radolyn.ayugram.proprietary.AyuMessageUtils to map Telegram TLRPC.Message data into AyuMessageBase rows and back, and posts AyuConstants.MESSAGE_EDITED_NOTIFICATION after edit revisions are inserted. It skips saving when AyuConfig.saveEditedMessageFor() or saveDeletedMessageFor() says the feature is disabled or the dialog is a bot excluded by saveForBots. Deleted messages are deduplicated by (userId, dialogId, topicId, messageId) and can carry persisted reactions when saveReactions is enabled. ui/AyuMessageHistory.java renders edit revisions by reconstructing TLRPC.TL_message objects through the proprietary mapper, and ui/AyuMessageCell.java opens saved media or copies saved text.
Ghost-mode and read-state behavior is split between persistent flags and short-lived allowances. AyuConfig.setGhostMode() flips packet-sending flags, while utils/AyuState.java holds one-shot counters for allowing read packets, marking automatically scheduled sends, hiding selection, and permitting local deletions. utils/AyuGhostUtils.java routes read requests: markReadOnServer() builds either TL_channels_readHistory or TL_messages_readHistory, temporarily allows one read packet, and processes affected-message PTS; markReadLocally() updates MessagesController.dialogs_read_inbox_max and MessagesStorage without a server packet. It also converts InputPeer/InputChannel into Telegram dialog IDs and extracts dialog/message IDs from read-history request objects.
Forwarding and synchronous send helpers exist to preserve deleted or no-forward messages by re-uploading content instead of using Telegram forwarding. AyuForwarder.java detects messages flagged messageOwner.ayuDeleted, messageOwner.ayuNoforwards, or chats marked ayuNoforwards, batches normal versus Ayu-forward messages, downloads needed media through AyuEasyUtils.loadDocumentsSync(), and sends text/documents/photos with generated group IDs for albums. easy/AyuEasyUtils.java wraps SendMessagesHelper and FileLoader calls in blocking helpers. Its EasyWaiter subclasses subscribe to NotificationCenter file/message events and wait on a CountDownLatch until send/upload/download completion or failure notification.
AyuSync is an optional WebSocket/HTTP sync layer. sync/AyuSyncConfig.java constructs HTTP and WebSocket URLs from AyuConfig.getSyncServerURL() and useSecureConnection, and sync/AyuInterceptor.java adds X-APP-PACKAGE plus Authorization headers to HTTP calls. sync/AyuSyncController.java runs on a dedicated DispatchQueue, loads activated Telegram accounts from UserConfig, verifies a token by calling /user/v1, requires AyuUser.isMVP, registers the device at /sync/register/v1 with AyuUtils.getDeviceName() and getDeviceIdentifier(), then creates AyuSyncWebSocketClient.java. The WebSocket sends the package, device identifier, and token headers, records last-sent/received timestamps in AyuSyncState.java, and dispatches JSON events back to AyuSyncController.invokeHandler(). Current handled sync payloads are sync_force, sync_batch, and sync_read from sync/models/*; force sync emits current dialog read states, while incoming sync_read applies local read state through AyuGhostUtils.markReadLocally().
Path-routing notes: AyuGram-owned Java lives under com.radolyn.ayugram, but several entry points are meant to be called by patched Telegram classes outside this ownership boundary. Static notification IDs and drawer/menu option IDs are centralized in AyuConstants.java; if an external caller routes on those constants, it should not duplicate raw numbers. Localized AyuGram UI strings are isolated in each values*/ayu.xml, so adding a preference row in ui/preferences/* should add the base key in values/ayu.xml and update translations as needed. messages/AyuMessagesController.java and ui/AyuMessageHistory.java depend on the proprietary AyuMessageUtils package even though that package is not present under the covered source tree; that mapper is the path between Telegram TLRPC objects and AyuGram database rows.
Coupling
- If database/…/AyuMessageBase.java changes, update both sides of
com.radolyn.ayugram.proprietary.AyuMessageUtils: messages/AyuMessagesController.java writes rows through it, and ui/AyuMessageHistory.java reconstructsTLRPC.Messageobjects through it. A schema-only change can otherwise save rows that the history UI cannot render. - If
AyuConstants.DOCUMENT_TYPE_*or media fields in AyuMessageBase.java change, verify AyuMessagesController.java, AyuMessageHistory.java, and AyuMessageCell.java; the UI decides whether to reuse Telegram cached media or open saved media paths from those fields. - If AyuSync JSON models in sync/…/*.java change, update
AyuSyncController.invokeHandler()and the server contract together. The controller switches on literal strings (sync_force,sync_batch,sync_read) and deserializes rawJsonObject/Gson payloads without a schema migration layer. - If ghost/read behavior is changed, verify both utils/AyuGhostUtils.java and utils/AyuState.java.
markReadOnServer()intentionally sets a one-shot read-packet allowance before sending Telegram read-history requests, whilemarkReadLocally()mutatesMessagesControllerandMessagesStoragewithout network traffic. - If forwarding behavior changes in AyuForwarder.java, verify the blocking send/download waiters in
easy/*. Album forwarding relies onAyuEasyUtils.createParams()group IDs and waits only for the final item in grouped sends. - If a preference key is renamed in AyuConfig.java, update all preference screens that persist it (
ui/preferences/*) and any default reads. The module uses raw string keys rather than generated constants. - If values/ayu.xml adds or renames an Ayu string, update the locale-specific values-*/ayu.xml files because the AyuGram preference and message-history UI use
LocaleController.getString(R.string.*)directly.
Risks
- database/AyuData.java builds the Room database with
fallbackToDestructiveMigration(), and AyuDatabase.java is already at version 21. If the schema changes without an explicit migration, existing deleted-message and edit-history rows can be silently wiped on upgrade. - database/AyuData.java uses
allowMainThreadQueries(), and messages/AyuMessagesController.java performs inserts, existence checks, deletes, and media file deletion synchronously. Large histories or slow storage can block UI paths that call these facades. - ui/…/AyuGramPreferencesActivity.java saves the WAL toggle under
"WALMode", but AyuConfig.java loads"walMode". Changing or relying on this toggle can appear ineffective because the saved key and loaded key do not match. - easy/EasyWaiter.java waits indefinitely on a
CountDownLatch; DummyMessageWaiter.java, DummyFileLoadWaiter.java, and DummyFileUploadWaiter.java only release when matchingNotificationCenterevents arrive. If Telegram changes notification names, argument shapes, or matching file-path formats, AyuForwarder.java can hang while re-sending restricted messages. - sync/AyuSyncController.java assumes
accounts.get(req.userId)returns an account afteraccountExists()and then callsMessagesController.getInstance(accountId). If async_batchevent contains mixed or malformed nesteduserIdvalues, a null account mapping can break sync handling before later events are processed.