diff --git a/documentation/extensions/index.md b/documentation/extensions/index.md index 0223d1554..78a2bbc57 100644 --- a/documentation/extensions/index.md +++ b/documentation/extensions/index.md @@ -14,6 +14,7 @@ Currently supported XEPs of Smack (all sub-projects) | Name | XEP | Version | Description | |---------------------------------------------|--------------------------------------------------------|-----------|----------------------------------------------------------------------------------------------------------| +| Discovering Alternative XMPP Connection Methods | [XEP-0156](https://xmpp.org/extensions/xep-0156.html) | 1.3.0 | Defines ways to discover alternative connection methods. | | Nonzas | [XEP-0360](https://xmpp.org/extensions/xep-0360.html) | n/a | Defines the term "Nonza", describing every top level stream element that is not a Stanza. | Currently supported XEPs of smack-tcp diff --git a/smack-core/src/main/java/org/jivesoftware/smack/altconnections/HttpLookupMethod.java b/smack-core/src/main/java/org/jivesoftware/smack/altconnections/HttpLookupMethod.java new file mode 100644 index 000000000..75a4cf263 --- /dev/null +++ b/smack-core/src/main/java/org/jivesoftware/smack/altconnections/HttpLookupMethod.java @@ -0,0 +1,176 @@ +/** + * + * Copyright 2020 Aditya Borikar. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.jivesoftware.smack.altconnections; + +import java.io.FileNotFoundException; +import java.io.IOException; +import java.io.InputStream; +import java.net.URI; +import java.net.URISyntaxException; +import java.net.URL; +import java.net.URLConnection; +import java.util.ArrayList; +import java.util.List; + +import org.jivesoftware.smack.util.PacketParserUtils; +import org.jivesoftware.smack.xml.XmlPullParser; +import org.jivesoftware.smack.xml.XmlPullParserException; + +import org.jxmpp.jid.DomainBareJid; + +/** + * The HTTP lookup method uses web host metadata to list the URIs of alternative connection methods. + * + *

In order to obtain host-meta XRD element from the host in the form of an InputStream, + * use {@link #getXrdStream(DomainBareJid)} method. To obtain endpoints for Bosh or Websocket + * connection endpoints from host, use {@link LinkRelation#BOSH} and {@link LinkRelation#WEBSOCKET} + * respectively with the {@link #lookup(DomainBareJid, LinkRelation)} method. In case one is looking + * for endpoints described by other than BOSH or Websocket LinkRelation, use the more flexible + * {@link #lookup(DomainBareJid, String)} method.

+ * Example:
+ * 
+ * {@code
+ * DomainBareJid xmppServerAddress = JidCreate.domainBareFrom("example.org");
+ * List endpoints = HttpLookupMethod.lookup(xmppServiceAddress, LinkRelation.WEBSOCKET);
+ * }
+ *
+ * @see + * HTTP Lookup Method from XEP-0156. + * + */ +public final class HttpLookupMethod { + private static final String XRD_NAMESPACE = "http://docs.oasis-open.org/ns/xri/xrd-1.0"; + + /** + * Specifies a link relation for the selected type of connection. + */ + public enum LinkRelation { + /** + * Selects link relation attribute as "urn:xmpp:alt-connections:xbosh". + */ + BOSH("urn:xmpp:alt-connections:xbosh"), + /** + * Selects link relation attribute as "urn:xmpp:alt-connections:websocket". + */ + WEBSOCKET("urn:xmpp:alt-connections:websocket"); + private final String attribute; + LinkRelation(String relAttribute) { + this.attribute = relAttribute; + } + } + + /** + * Get remote endpoints for the given LinkRelation from host. + * + * @param xmppServiceAddress address of host + * @param relation LinkRelation as a string specifying type of connection + * @return list of endpoints + * @throws IOException exception due to input/output operations + * @throws XmlPullParserException exception encountered during XML parsing + * @throws URISyntaxException exception to indicate that a string could not be parsed as a URI reference + */ + public static List lookup(DomainBareJid xmppServiceAddress, String relation) throws IOException, XmlPullParserException, URISyntaxException { + try (InputStream inputStream = getXrdStream(xmppServiceAddress)) { + XmlPullParser xmlPullParser = PacketParserUtils.getParserFor(inputStream); + List endpoints = parseXrdLinkReferencesFor(xmlPullParser, relation); + return endpoints; + } + } + + /** + * Get remote endpoints for the given LinkRelation from host. + * + * @param xmppServiceAddress address of host + * @param relation {@link LinkRelation} specifying type of connection + * @return list of endpoints + * @throws IOException exception due to input/output operations + * @throws XmlPullParserException exception encountered during XML parsing + * @throws URISyntaxException exception to indicate that a string could not be parsed as a URI reference + */ + public static List lookup(DomainBareJid xmppServiceAddress, LinkRelation relation) throws IOException, XmlPullParserException, URISyntaxException { + return lookup(xmppServiceAddress, relation.attribute); + } + + /** + * Constructs a HTTP connection with the host specified by the DomainBareJid + * and retrieves XRD element in the form of an InputStream. The method will + * throw a {@link FileNotFoundException} if host-meta isn't published. + * + * @param xmppServiceAddress address of host + * @return InputStream containing XRD element + * @throws IOException exception due to input/output operations + */ + public static InputStream getXrdStream(DomainBareJid xmppServiceAddress) throws IOException { + final String metadataUrl = "https://" + xmppServiceAddress + "/.well-known/host-meta"; + final URL putUrl = new URL(metadataUrl); + final URLConnection urlConnection = putUrl.openConnection(); + return urlConnection.getInputStream(); + } + + /** + * Get remote endpoints for the provided LinkRelation from provided XmlPullParser. + * + * @param parser XmlPullParser that contains LinkRelations + * @param relation type of endpoints specified by the given LinkRelation + * @return list of endpoints + * @throws IOException exception due to input/output operations + * @throws XmlPullParserException exception encountered during XML parsing + * @throws URISyntaxException exception to indicate that a string could not be parsed as a URI reference + */ + public static List parseXrdLinkReferencesFor(XmlPullParser parser, String relation) throws IOException, XmlPullParserException, URISyntaxException { + List uriList = new ArrayList<>(); + int initialDepth = parser.getDepth(); + + loop: while (true) { + XmlPullParser.TagEvent tag = parser.nextTag(); + switch (tag) { + case START_ELEMENT: + String name = parser.getName(); + String namespace = parser.getNamespace(); + String rel = parser.getAttributeValue("rel"); + + if (!namespace.equals(XRD_NAMESPACE) || !name.equals("Link") || !rel.equals(relation)) { + continue loop; + } + String endpointUri = parser.getAttributeValue("href"); + URI uri = new URI(endpointUri); + uriList.add(uri); + break; + case END_ELEMENT: + if (parser.getDepth() == initialDepth) { + break loop; + } + break; + } + } + return uriList; + } + + /** + * Get remote endpoints for the provided LinkRelation from provided XmlPullParser. + * + * @param parser XmlPullParser that contains LinkRelations + * @param relation type of endpoints specified by the given LinkRelation + * @return list of endpoints + * @throws IOException exception due to input/output operations + * @throws XmlPullParserException exception encountered during XML parsing + * @throws URISyntaxException exception to indicate that a string could not be parsed as a URI reference + */ + public static List parseXrdLinkReferencesFor(XmlPullParser parser, LinkRelation relation) throws IOException, XmlPullParserException, URISyntaxException { + return parseXrdLinkReferencesFor(parser, relation.attribute); + } +} diff --git a/smack-core/src/main/java/org/jivesoftware/smack/altconnections/package-info.java b/smack-core/src/main/java/org/jivesoftware/smack/altconnections/package-info.java new file mode 100644 index 000000000..5d9955232 --- /dev/null +++ b/smack-core/src/main/java/org/jivesoftware/smack/altconnections/package-info.java @@ -0,0 +1,22 @@ +/** + * + * Copyright 2020 Aditya Borikar. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +/** + * Smack's API for XEP-0156: Discovering Alternative XMPP Connection Methods. + *
+ * XEP is partially supported as HTTP lookup is supported but DNS lookup isn't. + */ +package org.jivesoftware.smack.altconnections; diff --git a/smack-core/src/test/java/org/jivesoftware/smack/altconnections/HttpLookupMethodTest.java b/smack-core/src/test/java/org/jivesoftware/smack/altconnections/HttpLookupMethodTest.java new file mode 100644 index 000000000..efa503ac1 --- /dev/null +++ b/smack-core/src/test/java/org/jivesoftware/smack/altconnections/HttpLookupMethodTest.java @@ -0,0 +1,57 @@ +/** + * + * Copyright 2020 Aditya Borikar. + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ +package org.jivesoftware.smack.altconnections; + +import static org.junit.jupiter.api.Assertions.assertEquals; + +import java.io.IOException; +import java.net.URI; +import java.net.URISyntaxException; +import java.util.ArrayList; +import java.util.List; + +import org.jivesoftware.smack.altconnections.HttpLookupMethod.LinkRelation; +import org.jivesoftware.smack.util.PacketParserUtils; +import org.jivesoftware.smack.xml.XmlPullParserException; + +import org.junit.jupiter.api.Test; +import org.jxmpp.stringprep.XmppStringprepException; + +public class HttpLookupMethodTest { + private static final String XRD_XML = "" + + "" + + "" + + "" + + ""; + + @Test + public void parseXrdLinkReferencesForWebsockets() throws XmppStringprepException, IOException, XmlPullParserException, URISyntaxException { + List endpoints = new ArrayList<>(); + endpoints.add(new URI("wss://xmpp.igniterealtime.org:7483/ws/")); + endpoints.add(new URI("ws://xmpp.igniterealtime.org:7070/ws/")); + List expectedEndpoints = HttpLookupMethod.parseXrdLinkReferencesFor(PacketParserUtils.getParserFor(XRD_XML), LinkRelation.WEBSOCKET); + assertEquals(expectedEndpoints, endpoints); + } + + @Test + public void parseXrdLinkReferencesForBosh() throws URISyntaxException, IOException, XmlPullParserException { + List endpoints = new ArrayList<>(); + endpoints.add(new URI("https://igniterealtime.org:443/http-bind/")); + List expectedEndpoints = HttpLookupMethod.parseXrdLinkReferencesFor(PacketParserUtils.getParserFor(XRD_XML), LinkRelation.BOSH); + assertEquals(expectedEndpoints, endpoints); + } +}