Merge pull request #401 from adiaholic/xep-0156

Add support for HTTP lookup method through XEP-0156

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

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.
+ *
+ * <p>In order to obtain host-meta XRD element from the host in the form of an <i>InputStream</i>,
+ * 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.</p>
+ * Example:<br>
+ * <pre>
+ * {@code
+ * DomainBareJid xmppServerAddress = JidCreate.domainBareFrom("example.org");
+ * List<URI> endpoints = HttpLookupMethod.lookup(xmppServiceAddress, LinkRelation.WEBSOCKET);
+ * }
+ * </pre>
+ * @see <a href="https://xmpp.org/extensions/xep-0156.html#http">
+ *     HTTP Lookup Method from XEP-0156.
+ *     </a>
+ */
+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<URI> lookup(DomainBareJid xmppServiceAddress, String relation) throws IOException, XmlPullParserException, URISyntaxException {
+        try (InputStream inputStream = getXrdStream(xmppServiceAddress)) {
+            XmlPullParser xmlPullParser = PacketParserUtils.getParserFor(inputStream);
+            List<URI> 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<URI> 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<URI> parseXrdLinkReferencesFor(XmlPullParser parser, String relation) throws IOException, XmlPullParserException, URISyntaxException {
+        List<URI> 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<URI> parseXrdLinkReferencesFor(XmlPullParser parser, LinkRelation relation) throws IOException, XmlPullParserException, URISyntaxException {
+        return parseXrdLinkReferencesFor(parser, relation.attribute);
+    }
+}

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 <a href="https://xmpp.org/extensions/xep-0156.html"> XEP-0156: Discovering Alternative XMPP Connection Methods</a>.
+ * <br>
+ * XEP is partially supported as HTTP lookup is supported but DNS lookup isn't.
+ */
+package org.jivesoftware.smack.altconnections;

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 = "<XRD xmlns='http://docs.oasis-open.org/ns/xri/xrd-1.0'>" +
+                    "<Link rel='urn:xmpp:alt-connections:xbosh' href='https://igniterealtime.org:443/http-bind/'/>" +
+                    "<Link rel='urn:xmpp:alt-connections:websocket' href='wss://xmpp.igniterealtime.org:7483/ws/'/>" +
+                    "<Link rel='urn:xmpp:alt-connections:websocket' href='ws://xmpp.igniterealtime.org:7070/ws/'/>" +
+                    "</XRD>";
+
+    @Test
+    public void parseXrdLinkReferencesForWebsockets() throws XmppStringprepException, IOException, XmlPullParserException, URISyntaxException {
+        List<URI> endpoints = new ArrayList<>();
+        endpoints.add(new URI("wss://xmpp.igniterealtime.org:7483/ws/"));
+        endpoints.add(new URI("ws://xmpp.igniterealtime.org:7070/ws/"));
+        List<URI> expectedEndpoints = HttpLookupMethod.parseXrdLinkReferencesFor(PacketParserUtils.getParserFor(XRD_XML), LinkRelation.WEBSOCKET);
+        assertEquals(expectedEndpoints, endpoints);
+    }
+
+    @Test
+    public void parseXrdLinkReferencesForBosh() throws URISyntaxException, IOException, XmlPullParserException {
+        List<URI> endpoints = new ArrayList<>();
+        endpoints.add(new URI("https://igniterealtime.org:443/http-bind/"));
+        List<URI> expectedEndpoints = HttpLookupMethod.parseXrdLinkReferencesFor(PacketParserUtils.getParserFor(XRD_XML), LinkRelation.BOSH);
+        assertEquals(expectedEndpoints, endpoints);
+    }
+}