Files
SHiNE-server/docs/API/09_Operations_Index.md
T

136 lines
15 KiB
Markdown

# API для разработчиков: индекс операций
Этот файл фиксирует полный список публичных JSON/WebSocket операций, зарегистрированных в коде сервера.
Источник истины на момент актуализации:
- `shine-server-net-protocol/src/main/java/server/logic/ws_protocol/JSON/JsonHandlerRegistry.java`.
Если операция есть в `HANDLERS` и `REQUEST_TYPES`, клиент может отправлять её как `op` в общем JSON-конверте из `00_Common_API_Format.md`.
## Актуальные операции
| Операция | Раздел документации | Кратко |
| --- | --- | --- |
| `GetNamespaces` | `01_User_Registration_API.md` | список namespace для регистрации |
| `CheckRegistrationLogin` | `01_User_Registration_API.md` | проверка полного логина |
| `CheckRegistrationEmail` | `01_User_Registration_API.md` | проверка доступности email |
| `StartFreeRegistration` | `01_User_Registration_API.md` | начало бесплатной регистрации с email-кодом |
| `ConfirmFreeRegistration` | `01_User_Registration_API.md` | подтверждение кода и выпуск сертификата |
| `GetRegistrationStatus` | `01_User_Registration_API.md` | статус регистрации |
| `GetUser` | `01_User_Registration_API.md` | чтение/проверка пользователя + server-состояние его блокчейна |
| `SearchUsers` | `01_User_Registration_API.md` | поиск логинов и публичных имён пользователей |
| `SearchChannels` | `06_Channels_Read_API.md` | поиск публичных каналов по названию, slug и логину владельца |
| `ResolveLoginForAuth` | `02_Authentication_API.md` | проверка login перед входом: LOCAL / REMOTE / NOT_FOUND / NO_ACCESS_SERVER + URL правильного access server |
| `AuthChallenge` | `02_Authentication_API.md` | challenge для создания новой сессии |
| `CreateAuthSession` | `02_Authentication_API.md` | создание новой авторизованной сессии |
| `SessionChallenge` | `02_Authentication_API.md` | challenge для входа в существующую сессию |
| `SessionLogin` | `02_Authentication_API.md` | вход в существующую сессию |
| `UpsertEspPairingSettings` | `03_Session_Management_API.md` | альтернативное имя настройки pairing; тот же обработчик, что `UpsertTrustedDeviceLoginSettings` |
| `StartEspPairing` | `03_Session_Management_API.md` | альтернативное имя начала pairing |
| `ListEspPairingRequests` | `03_Session_Management_API.md` | альтернативное имя списка заявок |
| `ApproveEspPairing` | `03_Session_Management_API.md` | альтернативное имя подтверждения |
| `RejectEspPairing` | `03_Session_Management_API.md` | альтернативное имя отклонения |
| `CancelEspPairing` | `03_Session_Management_API.md` | альтернативное имя отмены |
| `GetEspPairingStatus` | `03_Session_Management_API.md` | альтернативное имя чтения статуса |
| `GetTrustedDeviceLoginSettings` | `03_Session_Management_API.md` | чтение текущего режима входа через доверенное устройство |
| `UpsertTrustedDeviceLoginSettings` | `03_Session_Management_API.md` | включение/обновление pairing-настроек доверенной сессией |
| `StartTrustedDeviceLogin` | `03_Session_Management_API.md` | создание pairing-заявки для нового устройства |
| `ListTrustedDeviceLoginRequests` | `03_Session_Management_API.md` | список активных pairing-заявок для доверенной сессии |
| `ApproveTrustedDeviceLogin` | `03_Session_Management_API.md` | подтверждение pairing-заявки доверенной сессией |
| `RejectTrustedDeviceLogin` | `03_Session_Management_API.md` | отклонение pairing-заявки доверенной сессией |
| `CancelTrustedDeviceLogin` | `03_Session_Management_API.md` | отмена pairing-заявки со стороны нового ожидающего устройства |
| `GetTrustedDeviceLoginStatus` | `03_Session_Management_API.md` | чтение статуса и результата pairing-заявки |
| `ListSessions` | `03_Session_Management_API.md` | список активных сессий |
| `CloseActiveSession` | `03_Session_Management_API.md` | закрытие активной сессии |
| `CloseOtherSessions` | `03_Session_Management_API.md` | закрыть все остальные сессии текущего пользователя |
| `AddBlock` | `04_Add_Block_to_Blockchain_API.md` | добавление блока в блокчейн |
| `GetBlockchainBlock` | `04_Add_Block_to_Blockchain_API.md` | чтение одного блока блокчейна |
| `KeyRotationStart` | `19_Key_Rotation_API.md` | начать смену ключей сразу в состоянии `COPYING_CHAIN` |
| `KeyRotationStatus` | `19_Key_Rotation_API.md` | получить текущий этап и прогресс смены ключей |
| `KeyRotationAddBlock` | `19_Key_Rotation_API.md` | добавить подписанный новым blockchain key candidate-блок будущего fork |
| `KeyRotationFinishChain` | `19_Key_Rotation_API.md` | проверить полную публикацию candidate-chain и перевести её в `CHAIN_READY` |
| `KeyRotationRotatePda` | `19_Key_Rotation_API.md` | зафиксировать отправленную Solana-ротацию PDA и ждать подтверждения sync |
| `KeyRotationContinue` | `19_Key_Rotation_API.md` | зафиксировать wallet migration или завершить DM migration после серверной проверки |
| `KeyRotationAbort` | `19_Key_Rotation_API.md` | прервать ротацию до отправки Solana PDA-ротации |
| `GetMyBlockchain` | `20_Get_My_Blockchain_API.md` | постранично читать текущую активную собственную цепочку для аудита и выбора fork point |
| `ServerHello` | `16_Server_Connection_Pool_API.md` | объявление server-to-server соединения и возможностей peer без криптографической проверки |
| `Ping` | `05_Technical_Requests_API.md` | keep-alive |
| `GetServerInfo` | `05_Technical_Requests_API.md` | публичная информация о сервере |
| `ListBlockchainHeads` | `05_Technical_Requests_API.md` | список heads всех локальных блокчейнов |
| `GetSyncUserProfile` | `05_Technical_Requests_API.md` | межсерверный профиль пользователя для синхронизации |
| `SendSignal` | `05_Technical_Requests_API.md` | общий межсессионный технический сигнал в одну или все сессии пользователя |
| `GetCallIceConfig` | `05_Technical_Requests_API.md` | STUN/TURN конфигурация звонков |
| `ClientErrorLog` | `05_Technical_Requests_API.md` | логирование клиентской ошибки |
| `ClientDebugLog` | `05_Technical_Requests_API.md` | клиентский debug-лог |
| `CallDeliveryReport` | `05_Technical_Requests_API.md` | диагностика доставки/установки звонков |
| `ListSubscriptionsFeed` | `06_Channels_Read_API.md` | лента каналов/подписок |
| `GetChannelMessages` | `06_Channels_Read_API.md` | сообщения канала |
| `GetMessageThread` | `06_Channels_Read_API.md` | тред сообщения |
| `GetMessageLikes` | `06_Channels_Read_API.md` | списки пользователей, поставивших лайк сообщению |
| `GetPersonalDiary` | `06_Channels_Read_API.md` | виртуальный канал `Личный дневник` из STATUS_ACTION |
| `ListUserProfileChannels` | `06_Channels_Read_API.md` | публичные каналы профиля |
| `ListUserProfileRelations` | `11_Connections_API.md` | связи пользователя в профиле |
| `GetUserCounters` | `17_User_Counters_API.md` | счётчики пользователя |
| `GetChannelsCounters` | `06_Channels_Read_API.md` | счетчики разделов каналов |
| `SetChannelReadState` | `06_Channels_Read_API.md` | подписанный watermark чтения канала |
| `ListGroupChats200` | `06_Channels_Read_API.md` | список групповых чатов типа `200` |
| `GetGroupDialog` | `06_Channels_Read_API.md` | сообщения группового чата типа `200` |
| `UpsertUserParam` | `10_User_Params_API.md` | запись параметра пользователя |
| `GetUserParam` | `10_User_Params_API.md` | чтение одного параметра пользователя |
| `ListUserParams` | `10_User_Params_API.md` | список параметров пользователя |
| `UpsertUserSetting` | `13_User_Settings_API.md` | запись пользовательской настройки |
| `GetUserSetting` | `13_User_Settings_API.md` | чтение одной пользовательской настройки |
| `ListUserSettings` | `13_User_Settings_API.md` | список пользовательских настроек |
| `GetFriendsLists` | `11_Connections_API.md` | входящие/исходящие друзья |
| `ListContacts` | `11_Connections_API.md` | контакты текущего пользователя |
| `GetUserConnectionsGraph` | `11_Connections_API.md` | граф связей пользователя |
| `AddCloseFriend` | `11_Connections_API.md` | добавить близкого друга |
| `GetNotifications` | `15_Notifications_API.md` | ответы, связи, события и unread-watermark |
| `SetNotificationState` | `15_Notifications_API.md` | подписанное состояние просмотра уведомлений |
| `UpsertPushToken` | `12_Direct_Messages_Push_Calls_API.md` | регистрация WebPush-токена |
| `SendTestWebPush` | `12_Direct_Messages_Push_Calls_API.md` | тестовая push-доставка |
| `SendMessagePair` | `12_Direct_Messages_Push_Calls_API.md` | отправка пары входящий/исходящий DM |
| `ReceiveIncomingMessage` | `12_Direct_Messages_Push_Calls_API.md` | внутренняя доставка входящего DM-блока на единственный сервер получателя |
| `DeleteMessage` | `12_Direct_Messages_Push_Calls_API.md` | tombstone одного личного сообщения у обеих сторон |
| `DeleteConversation` | `12_Direct_Messages_Push_Calls_API.md` | tombstone удаления истории переписки |
| `GetDirectMessages` | `12_Direct_Messages_Push_Calls_API.md` | постраничная загрузка истории личного диалога; опциональный фильтр `reencryptedBeforeMs` |
| `ReencryptDirectMessage` | `12_Direct_Messages_Push_Calls_API.md` | сохранить локальную перешифрованную type=1/2 копию без federation |
| `AckSessionDelivery` | `12_Direct_Messages_Push_Calls_API.md` | подтверждение доставки в сессию |
| `CallInviteBroadcast` | `12_Direct_Messages_Push_Calls_API.md` | broadcast приглашения к звонку |
| `CallSignalToSession` | `12_Direct_Messages_Push_Calls_API.md` | сигнал звонка в конкретную сессию |
## Важные замечания
- UI отправляет полную подписанную пару только через `SendMessagePair`.
- `ReceiveIncomingMessage` вызывается сервером отправителя для доставки одной
входящей копии на единственный access-сервер получателя.
- Межсерверные DM-операции пока доверяют `sourceServerLogin`; отдельная межсерверная авторизация запланирована позднее.
- `ServerHello` пока принимает заявленный `serverLogin` на доверии и не является криптографической аутентификацией.
- HTTP endpoints зашифрованных DM-файлов (`PUT/GET/HEAD/OPTIONS /dm-files/{fileId}`) не являются WebSocket `op` и описаны отдельно в `18_DM_File_Storage_API.md`.
- HTTP endpoints публичных content-addressed файлов (`PUT/GET/HEAD/OPTIONS /files/{sha256}`) также не являются WebSocket `op` и описаны отдельно в `21_Public_File_Storage_API.md`.
- Закомментированный `ListSubscribedChannels` не зарегистрирован и не входит в публичный API. Классы `Net_MarkChannelMessagesSeen_*` существуют в коде, но операция `MarkChannelMessagesSeen` не зарегистрирована в `JsonHandlerRegistry`, поэтому в публичный список API не входит.
- HTTP debug endpoints из `src/main/java/server/debug/` не входят в этот индекс WebSocket `op`; они описаны отдельно в `13_HTTP_Debug_API.md`.
## Registration V2 (добавлено 23.10.2026, test/dev only)
- `GetNamespaces` — список зарегистрированных namespace из Solana-синхронизации;
- `CheckRegistrationLogin` — отдельная проверка `login@namespace`;
- `CheckRegistrationEmail` — отдельная проверка email;
- `StartFreeRegistration` — запрос сертификата по трём публичным ключам;
- `ConfirmFreeRegistration` — подтверждение тестовым кодом и Turbo ACK;
- `GetRegistrationStatus` — статус и публичные поля сертификата для upgrade.
Точный JSON и ограничения: [контракт регистрации v2](../registration-v2/WS_REGISTRATION_V2_API.md).
### `GetRegistrationStatus` после DB v35
Для существующего пользователя `payload.registrationStatus` имеет одно из **двух** значений:
`FREE_CERT` (бесплатная регистрация Arweave) или `PAID` (подтверждённая PDA Solana).
`PAID` применяется и к первоначально платным, и к ранее бесплатным пользователям;
`NOT_FOUND` остаётся техническим ответом для отсутствующего логина.
Во время поэтапного развертывания старый сервер может ещё возвращать `PAID_DIRECT`
или `PAID_UPGRADED`; обновлённый UI понимает эти устаревшие ответы как платные.
Поля сертификата для `FREE_CERT` и остальные поля API не меняются.