From 66b939e6b88598b5079a45e2ef601d832df823a3 Mon Sep 17 00:00:00 2001 From: Jonathan de Jong Date: Sun, 13 Feb 2022 17:14:14 +0100 Subject: [PATCH] ruma-appservice-api: Refactor file structure and docs --- .../src/event/push_events.rs | 198 +++++++++++++++++- .../src/event/push_events/v1.rs | 187 ----------------- crates/ruma-appservice-api/src/lib.rs | 2 +- .../src/query/query_room_alias.rs | 46 +++- .../src/query/query_room_alias/v1.rs | 39 ---- .../src/query/query_user_id.rs | 46 +++- .../src/query/query_user_id/v1.rs | 39 ---- .../thirdparty/get_location_for_protocol.rs | 56 ++++- .../get_location_for_protocol/v1.rs | 49 ----- .../thirdparty/get_location_for_room_alias.rs | 50 ++++- .../get_location_for_room_alias/v1.rs | 43 ---- .../src/thirdparty/get_protocol.rs | 49 ++++- .../src/thirdparty/get_protocol/v1.rs | 42 ---- .../src/thirdparty/get_user_for_protocol.rs | 56 ++++- .../thirdparty/get_user_for_protocol/v1.rs | 49 ----- .../src/thirdparty/get_user_for_user_id.rs | 50 ++++- .../src/thirdparty/get_user_for_user_id/v1.rs | 43 ---- 17 files changed, 544 insertions(+), 500 deletions(-) delete mode 100644 crates/ruma-appservice-api/src/event/push_events/v1.rs delete mode 100644 crates/ruma-appservice-api/src/query/query_room_alias/v1.rs delete mode 100644 crates/ruma-appservice-api/src/query/query_user_id/v1.rs delete mode 100644 crates/ruma-appservice-api/src/thirdparty/get_location_for_protocol/v1.rs delete mode 100644 crates/ruma-appservice-api/src/thirdparty/get_location_for_room_alias/v1.rs delete mode 100644 crates/ruma-appservice-api/src/thirdparty/get_protocol/v1.rs delete mode 100644 crates/ruma-appservice-api/src/thirdparty/get_user_for_protocol/v1.rs delete mode 100644 crates/ruma-appservice-api/src/thirdparty/get_user_for_user_id/v1.rs diff --git a/crates/ruma-appservice-api/src/event/push_events.rs b/crates/ruma-appservice-api/src/event/push_events.rs index 9bd3ae81..52f27dc6 100644 --- a/crates/ruma-appservice-api/src/event/push_events.rs +++ b/crates/ruma-appservice-api/src/event/push_events.rs @@ -1,3 +1,199 @@ +//! `PUT /_matrix/app/*/transactions/{txnId}` +//! //! Endpoint to push an event (or batch of events) to the application service. -pub mod v1; +pub mod v1 { + //! `/v1/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/application-service-api/#put_matrixappv1transactionstxnid + + use ruma_api::ruma_api; + use ruma_events::AnyRoomEvent; + use ruma_identifiers::TransactionId; + use ruma_serde::Raw; + + ruma_api! { + metadata: { + description: "This API is called by the homeserver when it wants to push an event (or batch of events) to the application service.", + method: PUT, + name: "push_events", + stable_path: "/_matrix/app/v1/transactions/:txn_id", + rate_limited: false, + authentication: QueryOnlyAccessToken, + added: 1.0, + } + + request: { + /// The transaction ID for this set of events. + /// + /// Homeservers generate these IDs and they are used to ensure idempotency of results. + #[ruma_api(path)] + pub txn_id: &'a TransactionId, + + /// A list of events. + pub events: &'a [Raw], + } + + #[derive(Default)] + response: {} + } + + impl<'a> Request<'a> { + /// Creates a new `Request` with the given transaction ID and list of events. + pub fn new(txn_id: &'a TransactionId, events: &'a [Raw]) -> Self { + Self { txn_id, events } + } + } + + impl IncomingRequest { + /// Creates an `IncomingRequest` with the given transaction ID and list of events. + pub fn new(txn_id: Box, events: Vec>) -> IncomingRequest { + IncomingRequest { txn_id, events } + } + + /// Consumes the `IncomingRequest` and tries to convert it to a `sync_events::Response` + /// + /// This is a helper conversion in cases where it's easier to work with + /// `sync_events::Response` instead of the original `push_events::IncomingRequest`. + /// It puts all events with a `room_id` into the `JoinedRoom`'s `timeline`. The + /// rationale behind that is that incoming Appservice transactions from the + /// homeserver are not necessarily bound to a specific user but can cover + /// a multitude of namespaces, and as such the Appservice basically only "observes joined + /// rooms". + /// + /// Note: Currently homeservers only push PDUs to appservices, no EDUs. There's the open + /// [MSC2409] regarding supporting EDUs in the future, though it seems to be planned to put + /// EDUs into a different JSON key than `events` to stay backwards compatible. + /// + /// [MSC2409]: https://github.com/matrix-org/matrix-doc/pull/2409 + #[cfg(feature = "helper")] + pub fn try_into_sync_response( + self, + next_batch: impl Into, + ) -> serde_json::Result { + use ruma_client_api::r0::sync::sync_events; + use ruma_identifiers::RoomId; + use serde::Deserialize; + use tracing::warn; + + #[derive(Debug, Deserialize)] + struct EventDeHelper { + room_id: Option>, + } + + let mut response = sync_events::Response::new(next_batch.into()); + + for raw_event in self.events { + let helper = raw_event.deserialize_as::()?; + let event_json = Raw::into_json(raw_event); + + if let Some(room_id) = helper.room_id { + let join = response.rooms.join.entry(room_id).or_default(); + join.timeline.events.push(Raw::from_json(event_json)); + } else { + warn!("Event without room_id: {}", event_json); + } + } + + Ok(response) + } + } + + impl Response { + /// Creates an empty `Response`. + pub fn new() -> Self { + Self {} + } + } + + #[cfg(feature = "helper")] + #[cfg(test)] + mod helper_tests { + use super::{AnyRoomEvent, IncomingRequest, Raw}; + use ruma_client_api::r0::sync::sync_events; + use ruma_identifiers::room_id; + use serde_json::json; + + #[test] + fn convert_incoming_request_to_sync_response() { + let txn_id = "any_txn_id".to_owned(); + let state_event: AnyRoomEvent = serde_json::from_value(json!({ + "content": {}, + "event_id": "$h29iv0s8:example.com", + "origin_server_ts": 1, + "room_id": "!roomid:room.com", + "sender": "@carl:example.com", + "state_key": "", + "type": "m.room.name" + })) + .unwrap(); + let message_event: AnyRoomEvent = serde_json::from_value(json!({ + "type": "m.room.message", + "event_id": "$143273582443PhrSn:example.com", + "origin_server_ts": 1, + "room_id": "!roomid:room.com", + "sender": "@user:example.com", + "content": { + "body": "test", + "msgtype": "m.audio", + "url": "mxc://example.com/AuDi0", + } + })) + .unwrap(); + + let events = vec![Raw::new(&state_event).unwrap(), Raw::new(&message_event).unwrap()]; + let incoming_request = IncomingRequest { txn_id: txn_id.clone(), events }; + + let response: sync_events::Response = + incoming_request.try_into_sync_response(txn_id).unwrap(); + + let response_rooms_join = response + .rooms + .join + .get(room_id!("!roomid:room.com")) + .expect("joined room response"); + + assert_eq!(response_rooms_join.timeline.events.len(), 2); + } + } + + #[cfg(feature = "server")] + #[cfg(test)] + mod tests { + use ruma_api::{OutgoingRequest, SendAccessToken}; + use serde_json::json; + + use super::Request; + + #[test] + fn decode_request_contains_events_field() { + let dummy_event = serde_json::from_value(json!({ + "type": "m.room.message", + "event_id": "$143273582443PhrSn:example.com", + "origin_server_ts": 1, + "room_id": "!roomid:room.com", + "sender": "@user:example.com", + "content": { + "body": "test", + "msgtype": "m.text", + }, + })) + .unwrap(); + let events = vec![dummy_event]; + + let req = Request { events: &events, txn_id: "any_txn_id".into() } + .try_into_http_request::>( + "https://homeserver.tld", + SendAccessToken::IfRequired("auth_tok"), + &[ruma_api::MatrixVersion::V1_1], + ) + .unwrap(); + let json_body: serde_json::Value = serde_json::from_slice(req.body()).unwrap(); + + assert_eq!( + 1, + json_body.as_object().unwrap().get("events").unwrap().as_array().unwrap().len() + ); + } + } +} diff --git a/crates/ruma-appservice-api/src/event/push_events/v1.rs b/crates/ruma-appservice-api/src/event/push_events/v1.rs deleted file mode 100644 index f23e77d8..00000000 --- a/crates/ruma-appservice-api/src/event/push_events/v1.rs +++ /dev/null @@ -1,187 +0,0 @@ -//! [PUT /_matrix/app/v1/transactions/{txnId}](https://matrix.org/docs/spec/application_service/r0.1.2#put-matrix-app-v1-transactions-txnid) - -use ruma_api::ruma_api; -use ruma_events::AnyRoomEvent; -use ruma_identifiers::TransactionId; -use ruma_serde::Raw; - -ruma_api! { - metadata: { - description: "This API is called by the homeserver when it wants to push an event (or batch of events) to the application service.", - method: PUT, - name: "push_events", - stable_path: "/_matrix/app/v1/transactions/:txn_id", - rate_limited: false, - authentication: QueryOnlyAccessToken, - added: 1.0, - } - - request: { - /// The transaction ID for this set of events. - /// - /// Homeservers generate these IDs and they are used to ensure idempotency of results. - #[ruma_api(path)] - pub txn_id: &'a TransactionId, - - /// A list of events. - pub events: &'a [Raw], - } - - #[derive(Default)] - response: {} -} - -impl<'a> Request<'a> { - /// Creates a new `Request` with the given transaction ID and list of events. - pub fn new(txn_id: &'a TransactionId, events: &'a [Raw]) -> Self { - Self { txn_id, events } - } -} - -impl IncomingRequest { - /// Creates an `IncomingRequest` with the given transaction ID and list of events. - pub fn new(txn_id: Box, events: Vec>) -> IncomingRequest { - IncomingRequest { txn_id, events } - } - - /// Consumes the `IncomingRequest` and tries to convert it to a `sync_events::Response` - /// - /// This is a helper conversion in cases where it's easier to work with `sync_events::Response` - /// instead of the original `push_events::IncomingRequest`. It puts all events with a `room_id` - /// into the `JoinedRoom`'s `timeline`. The rationale behind that is that incoming Appservice - /// transactions from the homeserver are not necessarily bound to a specific user but can cover - /// a multitude of namespaces, and as such the Appservice basically only "observes joined - /// rooms". - /// - /// Note: Currently homeservers only push PDUs to appservices, no EDUs. There's the open - /// [MSC2409] regarding supporting EDUs in the future, though it seems to be planned to put - /// EDUs into a different JSON key than `events` to stay backwards compatible. - /// - /// [MSC2409]: https://github.com/matrix-org/matrix-doc/pull/2409 - #[cfg(feature = "helper")] - pub fn try_into_sync_response( - self, - next_batch: impl Into, - ) -> serde_json::Result { - use ruma_client_api::r0::sync::sync_events; - use ruma_identifiers::RoomId; - use serde::Deserialize; - use tracing::warn; - - #[derive(Debug, Deserialize)] - struct EventDeHelper { - room_id: Option>, - } - - let mut response = sync_events::Response::new(next_batch.into()); - - for raw_event in self.events { - let helper = raw_event.deserialize_as::()?; - let event_json = Raw::into_json(raw_event); - - if let Some(room_id) = helper.room_id { - let join = response.rooms.join.entry(room_id).or_default(); - join.timeline.events.push(Raw::from_json(event_json)); - } else { - warn!("Event without room_id: {}", event_json); - } - } - - Ok(response) - } -} - -impl Response { - /// Creates an empty `Response`. - pub fn new() -> Self { - Self {} - } -} - -#[cfg(feature = "helper")] -#[cfg(test)] -mod helper_tests { - use super::{AnyRoomEvent, IncomingRequest, Raw}; - use ruma_client_api::r0::sync::sync_events; - use ruma_identifiers::room_id; - use serde_json::json; - - #[test] - fn convert_incoming_request_to_sync_response() { - let txn_id = "any_txn_id".to_owned(); - let state_event: AnyRoomEvent = serde_json::from_value(json!({ - "content": {}, - "event_id": "$h29iv0s8:example.com", - "origin_server_ts": 1, - "room_id": "!roomid:room.com", - "sender": "@carl:example.com", - "state_key": "", - "type": "m.room.name" - })) - .unwrap(); - let message_event: AnyRoomEvent = serde_json::from_value(json!({ - "type": "m.room.message", - "event_id": "$143273582443PhrSn:example.com", - "origin_server_ts": 1, - "room_id": "!roomid:room.com", - "sender": "@user:example.com", - "content": { - "body": "test", - "msgtype": "m.audio", - "url": "mxc://example.com/AuDi0", - } - })) - .unwrap(); - - let events = vec![Raw::new(&state_event).unwrap(), Raw::new(&message_event).unwrap()]; - let incoming_request = IncomingRequest { txn_id: txn_id.clone(), events }; - - let response: sync_events::Response = - incoming_request.try_into_sync_response(txn_id).unwrap(); - - let response_rooms_join = - response.rooms.join.get(room_id!("!roomid:room.com")).expect("joined room response"); - - assert_eq!(response_rooms_join.timeline.events.len(), 2); - } -} - -#[cfg(feature = "server")] -#[cfg(test)] -mod tests { - use ruma_api::{OutgoingRequest, SendAccessToken}; - use serde_json::json; - - use super::Request; - - #[test] - fn decode_request_contains_events_field() { - let dummy_event = serde_json::from_value(json!({ - "type": "m.room.message", - "event_id": "$143273582443PhrSn:example.com", - "origin_server_ts": 1, - "room_id": "!roomid:room.com", - "sender": "@user:example.com", - "content": { - "body": "test", - "msgtype": "m.text", - }, - })) - .unwrap(); - let events = vec![dummy_event]; - - let req = Request { events: &events, txn_id: "any_txn_id".into() } - .try_into_http_request::>( - "https://homeserver.tld", - SendAccessToken::IfRequired("auth_tok"), - &[ruma_api::MatrixVersion::V1_1], - ) - .unwrap(); - let json_body: serde_json::Value = serde_json::from_slice(req.body()).unwrap(); - - assert_eq!( - 1, - json_body.as_object().unwrap().get("events").unwrap().as_array().unwrap().len() - ); - } -} diff --git a/crates/ruma-appservice-api/src/lib.rs b/crates/ruma-appservice-api/src/lib.rs index 7359e2d6..e63f768e 100644 --- a/crates/ruma-appservice-api/src/lib.rs +++ b/crates/ruma-appservice-api/src/lib.rs @@ -3,7 +3,7 @@ //! (De)serializable types for the [Matrix Application Service API][appservice-api]. //! These types can be shared by application service and server code. //! -//! [appservice-api]: https://matrix.org/docs/spec/application_service/r0.1.2.html +//! [appservice-api]: https://spec.matrix.org/v1.2/application-service-api/ #![warn(missing_docs)] diff --git a/crates/ruma-appservice-api/src/query/query_room_alias.rs b/crates/ruma-appservice-api/src/query/query_room_alias.rs index 8c5ddc7f..9bfd3b1d 100644 --- a/crates/ruma-appservice-api/src/query/query_room_alias.rs +++ b/crates/ruma-appservice-api/src/query/query_room_alias.rs @@ -1,3 +1,47 @@ +//! `GET /_matrix/app/*/rooms/{roomAlias}` +//! //! Endpoint to query the existence of a given room alias. -pub mod v1; +pub mod v1 { + //! `/v1/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/application-service-api/#get_matrixappv1roomsroomalias + + use ruma_api::ruma_api; + use ruma_identifiers::RoomAliasId; + + ruma_api! { + metadata: { + description: "This endpoint is invoked by the homeserver on an application service to query the existence of a given room alias.", + method: GET, + name: "query_room_alias", + stable_path: "/_matrix/app/v1/rooms/:room_alias", + rate_limited: false, + authentication: QueryOnlyAccessToken, + added: 1.0, + } + + request: { + /// The room alias being queried. + #[ruma_api(path)] + pub room_alias: &'a RoomAliasId, + } + + #[derive(Default)] + response: {} + } + + impl<'a> Request<'a> { + /// Creates a new `Request` with the given room alias. + pub fn new(room_alias: &'a RoomAliasId) -> Self { + Self { room_alias } + } + } + + impl Response { + /// Create an empty `Response`. + pub fn new() -> Self { + Self {} + } + } +} diff --git a/crates/ruma-appservice-api/src/query/query_room_alias/v1.rs b/crates/ruma-appservice-api/src/query/query_room_alias/v1.rs deleted file mode 100644 index 65e25930..00000000 --- a/crates/ruma-appservice-api/src/query/query_room_alias/v1.rs +++ /dev/null @@ -1,39 +0,0 @@ -//! [GET /_matrix/app/v1/rooms/{roomAlias}](https://matrix.org/docs/spec/application_service/r0.1.2#get-matrix-app-v1-rooms-roomalias) - -use ruma_api::ruma_api; -use ruma_identifiers::RoomAliasId; - -ruma_api! { - metadata: { - description: "This endpoint is invoked by the homeserver on an application service to query the existence of a given room alias.", - method: GET, - name: "query_room_alias", - stable_path: "/_matrix/app/v1/rooms/:room_alias", - rate_limited: false, - authentication: QueryOnlyAccessToken, - added: 1.0, - } - - request: { - /// The room alias being queried. - #[ruma_api(path)] - pub room_alias: &'a RoomAliasId, - } - - #[derive(Default)] - response: {} -} - -impl<'a> Request<'a> { - /// Creates a new `Request` with the given room alias. - pub fn new(room_alias: &'a RoomAliasId) -> Self { - Self { room_alias } - } -} - -impl Response { - /// Create an empty `Response`. - pub fn new() -> Self { - Self {} - } -} diff --git a/crates/ruma-appservice-api/src/query/query_user_id.rs b/crates/ruma-appservice-api/src/query/query_user_id.rs index 5a7e3635..3b1c372f 100644 --- a/crates/ruma-appservice-api/src/query/query_user_id.rs +++ b/crates/ruma-appservice-api/src/query/query_user_id.rs @@ -1,3 +1,47 @@ +//! `GET /_matrix/app/*/users/{userId}` +//! //! Endpoint to query the existence of a given user ID. -pub mod v1; +pub mod v1 { + //! `/v1/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/application-service-api/#get_matrixappv1usersuserid + + use ruma_api::ruma_api; + use ruma_identifiers::UserId; + + ruma_api! { + metadata: { + description: "This endpoint is invoked by the homeserver on an application service to query the existence of a given user ID.", + method: GET, + name: "query_user_id", + stable_path: "/_matrix/app/v1/users/:user_id", + rate_limited: false, + authentication: QueryOnlyAccessToken, + added: 1.0, + } + + request: { + /// The user ID being queried. + #[ruma_api(path)] + pub user_id: &'a UserId, + } + + #[derive(Default)] + response: {} + } + + impl<'a> Request<'a> { + /// Creates a new `Request` with the given user id. + pub fn new(user_id: &'a UserId) -> Self { + Self { user_id } + } + } + + impl Response { + /// Creates an empty `Response`. + pub fn new() -> Self { + Self {} + } + } +} diff --git a/crates/ruma-appservice-api/src/query/query_user_id/v1.rs b/crates/ruma-appservice-api/src/query/query_user_id/v1.rs deleted file mode 100644 index e87831a0..00000000 --- a/crates/ruma-appservice-api/src/query/query_user_id/v1.rs +++ /dev/null @@ -1,39 +0,0 @@ -//! [GET /_matrix/app/v1/users/{userId}](https://matrix.org/docs/spec/application_service/r0.1.2#get-matrix-app-v1-users-userid) - -use ruma_api::ruma_api; -use ruma_identifiers::UserId; - -ruma_api! { - metadata: { - description: "This endpoint is invoked by the homeserver on an application service to query the existence of a given user ID.", - method: GET, - name: "query_user_id", - stable_path: "/_matrix/app/v1/users/:user_id", - rate_limited: false, - authentication: QueryOnlyAccessToken, - added: 1.0, - } - - request: { - /// The user ID being queried. - #[ruma_api(path)] - pub user_id: &'a UserId, - } - - #[derive(Default)] - response: {} -} - -impl<'a> Request<'a> { - /// Creates a new `Request` with the given user id. - pub fn new(user_id: &'a UserId) -> Self { - Self { user_id } - } -} - -impl Response { - /// Creates an empty `Response`. - pub fn new() -> Self { - Self {} - } -} diff --git a/crates/ruma-appservice-api/src/thirdparty/get_location_for_protocol.rs b/crates/ruma-appservice-api/src/thirdparty/get_location_for_protocol.rs index 778b543a..b778a4d7 100644 --- a/crates/ruma-appservice-api/src/thirdparty/get_location_for_protocol.rs +++ b/crates/ruma-appservice-api/src/thirdparty/get_location_for_protocol.rs @@ -1,4 +1,58 @@ +//! `GET /_matrix/app/*/thirdparty/location/{protocol}` +//! //! Endpoint to retrieve a list of Matrix portal rooms that lead to the matched third party //! location. -pub mod v1; +pub mod v1 { + //! `/v1/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/application-service-api/#get_matrixappv1thirdpartylocationprotocol + + use std::collections::BTreeMap; + + use ruma_api::ruma_api; + use ruma_common::thirdparty::Location; + + ruma_api! { + metadata: { + description: "Fetches third party locations for a protocol.", + method: GET, + name: "get_location_for_protocol", + stable_path: "/_matrix/app/v1/thirdparty/location/:protocol", + rate_limited: false, + authentication: QueryOnlyAccessToken, + added: 1.0, + } + + request: { + /// The protocol used to communicate to the third party network. + #[ruma_api(path)] + pub protocol: &'a str, + + /// One or more custom fields to help identify the third party location. + // The specification is incorrect for this parameter. See matrix-org/matrix-doc#2352. + #[ruma_api(query_map)] + pub fields: BTreeMap, + } + + response: { + /// List of matched third party locations. + #[ruma_api(body)] + pub locations: Vec, + } + } + + impl<'a> Request<'a> { + /// Creates a new `Request` with the given protocol. + pub fn new(protocol: &'a str) -> Self { + Self { protocol, fields: BTreeMap::new() } + } + } + + impl Response { + /// Creates a new `Response` with the given locations. + pub fn new(locations: Vec) -> Self { + Self { locations } + } + } +} diff --git a/crates/ruma-appservice-api/src/thirdparty/get_location_for_protocol/v1.rs b/crates/ruma-appservice-api/src/thirdparty/get_location_for_protocol/v1.rs deleted file mode 100644 index 25780d5a..00000000 --- a/crates/ruma-appservice-api/src/thirdparty/get_location_for_protocol/v1.rs +++ /dev/null @@ -1,49 +0,0 @@ -//! [GET /_matrix/app/v1/thirdparty/location/{protocol}](https://matrix.org/docs/spec/application_service/r0.1.2#get-matrix-app-v1-thirdparty-location-protocol) - -use std::collections::BTreeMap; - -use ruma_api::ruma_api; -use ruma_common::thirdparty::Location; - -ruma_api! { - metadata: { - description: "Fetches third party locations for a protocol.", - method: GET, - name: "get_location_for_protocol", - stable_path: "/_matrix/app/v1/thirdparty/location/:protocol", - rate_limited: false, - authentication: QueryOnlyAccessToken, - added: 1.0, - } - - request: { - /// The protocol used to communicate to the third party network. - #[ruma_api(path)] - pub protocol: &'a str, - - /// One or more custom fields to help identify the third party location. - // The specification is incorrect for this parameter. See matrix-org/matrix-doc#2352. - #[ruma_api(query_map)] - pub fields: BTreeMap, - } - - response: { - /// List of matched third party locations. - #[ruma_api(body)] - pub locations: Vec, - } -} - -impl<'a> Request<'a> { - /// Creates a new `Request` with the given protocol. - pub fn new(protocol: &'a str) -> Self { - Self { protocol, fields: BTreeMap::new() } - } -} - -impl Response { - /// Creates a new `Response` with the given locations. - pub fn new(locations: Vec) -> Self { - Self { locations } - } -} diff --git a/crates/ruma-appservice-api/src/thirdparty/get_location_for_room_alias.rs b/crates/ruma-appservice-api/src/thirdparty/get_location_for_room_alias.rs index ab8c405b..b721f30d 100644 --- a/crates/ruma-appservice-api/src/thirdparty/get_location_for_room_alias.rs +++ b/crates/ruma-appservice-api/src/thirdparty/get_location_for_room_alias.rs @@ -1,3 +1,51 @@ +//! `GET /_matrix/app/*/thirdparty/location` +//! //! Endpoint to retrieve an array of third party network locations from a Matrix room alias. -pub mod v1; +pub mod v1 { + //! `/v1/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/application-service-api/#get_matrixappv1thirdpartylocation + + use ruma_api::ruma_api; + use ruma_common::thirdparty::Location; + use ruma_identifiers::RoomAliasId; + + ruma_api! { + metadata: { + description: "Retrieve an array of third party network locations from a Matrix room alias.", + method: GET, + name: "get_location_for_room_alias", + stable_path: "/_matrix/app/v1/thirdparty/location", + rate_limited: false, + authentication: QueryOnlyAccessToken, + added: 1.0, + } + + request: { + /// The Matrix room alias to look up. + #[ruma_api(query)] + pub alias: &'a RoomAliasId, + } + + response: { + /// List of matched third party locations. + #[ruma_api(body)] + pub locations: Vec, + } + } + + impl<'a> Request<'a> { + /// Creates a new `Request` with the given room alias id. + pub fn new(alias: &'a RoomAliasId) -> Self { + Self { alias } + } + } + + impl Response { + /// Creates a new `Response` with the given locations. + pub fn new(locations: Vec) -> Self { + Self { locations } + } + } +} diff --git a/crates/ruma-appservice-api/src/thirdparty/get_location_for_room_alias/v1.rs b/crates/ruma-appservice-api/src/thirdparty/get_location_for_room_alias/v1.rs deleted file mode 100644 index 11d9a35f..00000000 --- a/crates/ruma-appservice-api/src/thirdparty/get_location_for_room_alias/v1.rs +++ /dev/null @@ -1,43 +0,0 @@ -//! [GET /_matrix/app/v1/thirdparty/location](https://matrix.org/docs/spec/application_service/r0.1.2#get-matrix-app-v1-thirdparty-location) - -use ruma_api::ruma_api; -use ruma_common::thirdparty::Location; -use ruma_identifiers::RoomAliasId; - -ruma_api! { - metadata: { - description: "Retrieve an array of third party network locations from a Matrix room alias.", - method: GET, - name: "get_location_for_room_alias", - stable_path: "/_matrix/app/v1/thirdparty/location", - rate_limited: false, - authentication: QueryOnlyAccessToken, - added: 1.0, - } - - request: { - /// The Matrix room alias to look up. - #[ruma_api(query)] - pub alias: &'a RoomAliasId, - } - - response: { - /// List of matched third party locations. - #[ruma_api(body)] - pub locations: Vec, - } -} - -impl<'a> Request<'a> { - /// Creates a new `Request` with the given room alias id. - pub fn new(alias: &'a RoomAliasId) -> Self { - Self { alias } - } -} - -impl Response { - /// Creates a new `Response` with the given locations. - pub fn new(locations: Vec) -> Self { - Self { locations } - } -} diff --git a/crates/ruma-appservice-api/src/thirdparty/get_protocol.rs b/crates/ruma-appservice-api/src/thirdparty/get_protocol.rs index 3b3c1319..035176c2 100644 --- a/crates/ruma-appservice-api/src/thirdparty/get_protocol.rs +++ b/crates/ruma-appservice-api/src/thirdparty/get_protocol.rs @@ -1,4 +1,51 @@ +//! `GET /_matrix/app/*/thirdparty/protocol/{protocol}` +//! //! Endpoint to present clients with specific information about the various third party networks //! that an application service supports. -pub mod v1; +pub mod v1 { + //! `/v1/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol + + use ruma_api::ruma_api; + use ruma_common::thirdparty::Protocol; + + ruma_api! { + metadata: { + description: "Fetches the metadata from the homeserver about a particular third party protocol.", + method: GET, + name: "get_protocol", + stable_path: "/_matrix/app/v1/thirdparty/protocol/:protocol", + rate_limited: false, + authentication: QueryOnlyAccessToken, + added: 1.0, + } + + request: { + /// The name of the protocol. + #[ruma_api(path)] + pub protocol: &'a str, + } + + response: { + /// Metadata about the protocol. + #[ruma_api(body)] + pub protocol: Protocol, + } + } + + impl<'a> Request<'a> { + /// Creates a new `Request` with the given protocol name. + pub fn new(protocol: &'a str) -> Self { + Self { protocol } + } + } + + impl Response { + /// Creates a new `Response` with the given protocol. + pub fn new(protocol: Protocol) -> Self { + Self { protocol } + } + } +} diff --git a/crates/ruma-appservice-api/src/thirdparty/get_protocol/v1.rs b/crates/ruma-appservice-api/src/thirdparty/get_protocol/v1.rs deleted file mode 100644 index 30c399de..00000000 --- a/crates/ruma-appservice-api/src/thirdparty/get_protocol/v1.rs +++ /dev/null @@ -1,42 +0,0 @@ -//! [GET /_matrix/app/v1/thirdparty/protocol/{protocol}](https://matrix.org/docs/spec/application_service/r0.1.2#get-matrix-app-v1-thirdparty-protocol-protocol) - -use ruma_api::ruma_api; -use ruma_common::thirdparty::Protocol; - -ruma_api! { - metadata: { - description: "Fetches the metadata from the homeserver about a particular third party protocol.", - method: GET, - name: "get_protocol", - stable_path: "/_matrix/app/v1/thirdparty/protocol/:protocol", - rate_limited: false, - authentication: QueryOnlyAccessToken, - added: 1.0, - } - - request: { - /// The name of the protocol. - #[ruma_api(path)] - pub protocol: &'a str, - } - - response: { - /// Metadata about the protocol. - #[ruma_api(body)] - pub protocol: Protocol, - } -} - -impl<'a> Request<'a> { - /// Creates a new `Request` with the given protocol name. - pub fn new(protocol: &'a str) -> Self { - Self { protocol } - } -} - -impl Response { - /// Creates a new `Response` with the given protocol. - pub fn new(protocol: Protocol) -> Self { - Self { protocol } - } -} diff --git a/crates/ruma-appservice-api/src/thirdparty/get_user_for_protocol.rs b/crates/ruma-appservice-api/src/thirdparty/get_user_for_protocol.rs index cad14a5e..5953ca69 100644 --- a/crates/ruma-appservice-api/src/thirdparty/get_user_for_protocol.rs +++ b/crates/ruma-appservice-api/src/thirdparty/get_user_for_protocol.rs @@ -1,4 +1,58 @@ +//! `GET /_matrix/app/*/thirdparty/user/{protocol}` +//! //! Endpoint to retrieve a Matrix User ID linked to a user on the third party network, given a set //! of user parameters. -pub mod v1; +pub mod v1 { + //! `/v1/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/application-service-api/#get_matrixappv1thirdpartyuserprotocol + + use std::collections::BTreeMap; + + use ruma_api::ruma_api; + use ruma_common::thirdparty::User; + + ruma_api! { + metadata: { + description: "Fetches third party users for a protocol.", + method: GET, + name: "get_user_for_protocol", + stable_path: "/_matrix/app/v1/thirdparty/user/:protocol", + rate_limited: false, + authentication: QueryOnlyAccessToken, + added: 1.0, + } + + request: { + /// The protocol used to communicate to the third party network. + #[ruma_api(path)] + pub protocol: &'a str, + + /// One or more custom fields that are passed to the AS to help identify the user. + // The specification is incorrect for this parameter. See matrix-org/matrix-doc#2352. + #[ruma_api(query_map)] + pub fields: BTreeMap, + } + + response: { + /// List of matched third party users. + #[ruma_api(body)] + pub users: Vec, + } + } + + impl<'a> Request<'a> { + /// Creates a new `Request` with the given protocol name. + pub fn new(protocol: &'a str) -> Self { + Self { protocol, fields: BTreeMap::new() } + } + } + + impl Response { + /// Creates a new `Response` with the given users. + pub fn new(users: Vec) -> Self { + Self { users } + } + } +} diff --git a/crates/ruma-appservice-api/src/thirdparty/get_user_for_protocol/v1.rs b/crates/ruma-appservice-api/src/thirdparty/get_user_for_protocol/v1.rs deleted file mode 100644 index 01fddea3..00000000 --- a/crates/ruma-appservice-api/src/thirdparty/get_user_for_protocol/v1.rs +++ /dev/null @@ -1,49 +0,0 @@ -//! [GET /_matrix/app/v1/thirdparty/user/{protocol}](https://matrix.org/docs/spec/application_service/r0.1.2#get-matrix-app-v1-thirdparty-user-protocol) - -use std::collections::BTreeMap; - -use ruma_api::ruma_api; -use ruma_common::thirdparty::User; - -ruma_api! { - metadata: { - description: "Fetches third party users for a protocol.", - method: GET, - name: "get_user_for_protocol", - stable_path: "/_matrix/app/v1/thirdparty/user/:protocol", - rate_limited: false, - authentication: QueryOnlyAccessToken, - added: 1.0, - } - - request: { - /// The protocol used to communicate to the third party network. - #[ruma_api(path)] - pub protocol: &'a str, - - /// One or more custom fields that are passed to the AS to help identify the user. - // The specification is incorrect for this parameter. See matrix-org/matrix-doc#2352. - #[ruma_api(query_map)] - pub fields: BTreeMap, - } - - response: { - /// List of matched third party users. - #[ruma_api(body)] - pub users: Vec, - } -} - -impl<'a> Request<'a> { - /// Creates a new `Request` with the given protocol name. - pub fn new(protocol: &'a str) -> Self { - Self { protocol, fields: BTreeMap::new() } - } -} - -impl Response { - /// Creates a new `Response` with the given users. - pub fn new(users: Vec) -> Self { - Self { users } - } -} diff --git a/crates/ruma-appservice-api/src/thirdparty/get_user_for_user_id.rs b/crates/ruma-appservice-api/src/thirdparty/get_user_for_user_id.rs index bc2d9a1d..48687f8d 100644 --- a/crates/ruma-appservice-api/src/thirdparty/get_user_for_user_id.rs +++ b/crates/ruma-appservice-api/src/thirdparty/get_user_for_user_id.rs @@ -1,3 +1,51 @@ +//! `GET /_matrix/app/*/thirdparty/user` +//! //! Endpoint to retrieve an array of third party users from a Matrix User ID. -pub mod v1; +pub mod v1 { + //! `/v1/` ([spec]) + //! + //! [spec]: https://spec.matrix.org/v1.2/application-service-api/#get_matrixappv1thirdpartyuser + + use ruma_api::ruma_api; + use ruma_common::thirdparty::User; + use ruma_identifiers::UserId; + + ruma_api! { + metadata: { + description: "Retrieve an array of third party users from a Matrix User ID.", + method: GET, + name: "get_user_for_user_id", + stable_path: "/_matrix/app/v1/thirdparty/user", + rate_limited: false, + authentication: QueryOnlyAccessToken, + added: 1.0, + } + + request: { + /// The Matrix User ID to look up. + #[ruma_api(query)] + pub userid: &'a UserId, + } + + response: { + /// List of matched third party users. + #[ruma_api(body)] + pub users: Vec, + } + } + + impl<'a> Request<'a> { + /// Creates a new `Request` with the given user id. + pub fn new(userid: &'a UserId) -> Self { + Self { userid } + } + } + + impl Response { + /// Creates a new `Response` with the given users. + pub fn new(users: Vec) -> Self { + Self { users } + } + } +} diff --git a/crates/ruma-appservice-api/src/thirdparty/get_user_for_user_id/v1.rs b/crates/ruma-appservice-api/src/thirdparty/get_user_for_user_id/v1.rs deleted file mode 100644 index 4f44408d..00000000 --- a/crates/ruma-appservice-api/src/thirdparty/get_user_for_user_id/v1.rs +++ /dev/null @@ -1,43 +0,0 @@ -//! [GET /_matrix/app/v1/thirdparty/user](https://matrix.org/docs/spec/application_service/r0.1.2#get-matrix-app-v1-thirdparty-user) - -use ruma_api::ruma_api; -use ruma_common::thirdparty::User; -use ruma_identifiers::UserId; - -ruma_api! { - metadata: { - description: "Retrieve an array of third party users from a Matrix User ID.", - method: GET, - name: "get_user_for_user_id", - stable_path: "/_matrix/app/v1/thirdparty/user", - rate_limited: false, - authentication: QueryOnlyAccessToken, - added: 1.0, - } - - request: { - /// The Matrix User ID to look up. - #[ruma_api(query)] - pub userid: &'a UserId, - } - - response: { - /// List of matched third party users. - #[ruma_api(body)] - pub users: Vec, - } -} - -impl<'a> Request<'a> { - /// Creates a new `Request` with the given user id. - pub fn new(userid: &'a UserId) -> Self { - Self { userid } - } -} - -impl Response { - /// Creates a new `Response` with the given users. - pub fn new(users: Vec) -> Self { - Self { users } - } -}