Add thirdparty network endpoints

src/v1.rs

@@ -2,3 +2,4 @@
 
 pub mod event;
 pub mod query;
+pub mod thirdparty;

src/v1/thirdparty.rs

@@ -0,0 +1,73 @@
+//! Endpoints for third party lookups
+
+pub mod get_location_for_protocol;
+pub mod get_location_for_room_alias;
+pub mod get_protocol;
+pub mod get_user_for_protocol;
+pub mod get_user_for_user_id;
+
+use std::collections::HashMap;
+
+use ruma_identifiers::{RoomAliasId, UserId};
+
+use serde::{Deserialize, Serialize};
+
+/// Metadata about a third party protocol.
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct Protocol {
+    /// Fields which may be used to identify a third party user.
+    pub user_fields: Vec<String>,
+    /// Fields which may be used to identify a third party location.
+    pub location_fields: Vec<String>,
+    /// A content URI representing an icon for the third party protocol.
+    pub icon: String,
+    /// The type definitions for the fields defined in `user_fields` and `location_fields`.
+    pub field_types: HashMap<String, FieldType>,
+    /// A list of objects representing independent instances of configuration.
+    pub instances: Vec<ProtocolInstance>,
+}
+
+/// Metadata about an instance of a third party protocol.
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct ProtocolInstance {
+    /// A human-readable description for the protocol, such as the name.
+    pub desc: String,
+    /// An optional content URI representing the protocol.
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub icon: Option<String>,
+    /// Preset values for `fields` the client may use to search by.
+    pub fields: HashMap<String, String>,
+    /// A unique identifier across all instances.
+    pub network_id: String,
+}
+
+/// A type definition for a field used to identify third party users or locations.
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct FieldType {
+    /// A regular expression for validation of a field's value.
+    pub regexp: String,
+    /// A placeholder serving as a valid example of the field value.
+    pub placeholder: String,
+}
+
+/// A third party network location.
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct Location {
+    /// An alias for a matrix room.
+    pub alias: RoomAliasId,
+    /// The protocol ID that the third party location is a part of.
+    pub protocol: String,
+    /// Information used to identify this third party location.
+    pub fields: HashMap<String, String>,
+}
+
+/// A third party network user.
+#[derive(Clone, Debug, Deserialize, Serialize)]
+pub struct User {
+    /// A matrix user ID representing a third party user.
+    pub userid: UserId,
+    /// The protocol ID that the third party user is a part of.
+    pub protocol: String,
+    /// Information used to identify this third party user.
+    pub fields: HashMap<String, String>,
+}

src/v1/thirdparty/get_location_for_protocol.rs

@@ -0,0 +1,34 @@
+//! [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::HashMap;
+
+use ruma_api::ruma_api;
+
+use super::Location;
+
+ruma_api! {
+    metadata {
+        description: "Fetches third party locations for a protocol.",
+        method: GET,
+        name: "get_location_for_protocol",
+        path: "/_matrix/app/v1/thirdparty/location/:protocol",
+        rate_limited: false,
+        requires_authentication: true,
+    }
+
+    request {
+        /// The protocol used to communicate to the third party network.
+        #[ruma_api(path)]
+        pub protocol: String,
+        /// 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: HashMap<String, String>,
+    }
+
+    response {
+        /// List of matched third party locations.
+        #[ruma_api(body)]
+        pub locations: Vec<Location>,
+    }
+}

src/v1/thirdparty/get_location_for_room_alias.rs

@@ -0,0 +1,29 @@
+//! [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_identifiers::RoomAliasId;
+
+use super::Location;
+
+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",
+        path: "/_matrix/app/v1/thirdparty/location",
+        rate_limited: false,
+        requires_authentication: true,
+    }
+
+    request {
+        /// The Matrix room alias to look up.
+        #[ruma_api(query)]
+        pub alias: RoomAliasId,
+    }
+
+    response {
+        /// List of matched third party locations.
+        #[ruma_api(body)]
+        pub locations: Vec<Location>,
+    }
+}

src/v1/thirdparty/get_protocol.rs

@@ -0,0 +1,28 @@
+//! [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 super::Protocol;
+
+ruma_api! {
+    metadata {
+        description: "Fetches the metadata from the homeserver about a particular third party protocol.",
+        method: GET,
+        name: "get_protocol",
+        path: "/_matrix/app/v1/thirdparty/protocol/:protocol",
+        rate_limited: false,
+        requires_authentication: true,
+    }
+
+    request {
+        /// The name of the protocol.
+        #[ruma_api(path)]
+        pub protocol: String,
+    }
+
+    response {
+        /// Metadata about the protocol.
+        #[ruma_api(body)]
+        pub protocol: Protocol,
+    }
+}

src/v1/thirdparty/get_user_for_protocol.rs

@@ -0,0 +1,34 @@
+//! [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::HashMap;
+
+use ruma_api::ruma_api;
+
+use super::User;
+
+ruma_api! {
+    metadata {
+        description: "Fetches third party users for a protocol.",
+        method: GET,
+        name: "get_user_for_protocol",
+        path: "/_matrix/app/v1/thirdparty/user/:protocol",
+        rate_limited: false,
+        requires_authentication: true,
+    }
+
+    request {
+        /// The protocol used to communicate to the third party network.
+        #[ruma_api(path)]
+        pub protocol: String,
+        /// 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: HashMap<String, String>,
+    }
+
+    response {
+        /// List of matched third party users.
+        #[ruma_api(body)]
+        pub users: Vec<User>,
+    }
+}

src/v1/thirdparty/get_user_for_user_id.rs

@@ -0,0 +1,29 @@
+//! [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_identifiers::UserId;
+
+use super::User;
+
+ruma_api! {
+    metadata {
+        description: "Retrieve an array of third party users from a Matrix User ID.",
+        method: GET,
+        name: "get_user_for_user_id",
+        path: "/_matrix/app/v1/thirdparty/user",
+        rate_limited: false,
+        requires_authentication: true,
+    }
+
+    request {
+        /// The Matrix User ID to look up.
+        #[ruma_api(query)]
+        pub userid: UserId,
+    }
+
+    response {
+        /// List of matched third party users.
+        #[ruma_api(body)]
+        pub users: Vec<User>,
+    }
+}