Add support to parse user-agents

Author: laurentpellegrino

CHANGELOG.md

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.7.0] - 2022-06-10
+### Added
+- Add new `parse` method to _IpregistryClient_ to parse one or more user-agent values.
+
 ## [3.6.0] - 2022-04-15
 ### Added
 - New `vpn` field in `security` object.
@@ -127,7 +131,8 @@ https://github.com/ipregistry/ipregistry-java#caching
 ## [1.0.0] - 2019-07-03
 - First public release.
 
-[Unreleased]: https://github.com/ipregistry/ipregistry-java/compare/v3.6.0...HEAD
+[Unreleased]: https://github.com/ipregistry/ipregistry-java/compare/v3.7.0...HEAD
+[3.7.0]: https://github.com/ipregistry/ipregistry-java/compare/v3.6.0...v3.7.0
 [3.6.0]: https://github.com/ipregistry/ipregistry-java/compare/v3.5.0...v3.6.0
 [3.5.0]: https://github.com/ipregistry/ipregistry-java/compare/v3.4.0...v3.5.0
 [3.4.0]: https://github.com/ipregistry/ipregistry-java/compare/v3.3.0...v3.4.0

src/integrationTest/java/co/ipregistry/api/client/integration/IpregistryClientIntegrationTest.java

@@ -4,10 +4,7 @@
 import co.ipregistry.api.client.exceptions.ApiException;
 import co.ipregistry.api.client.exceptions.ClientException;
 import co.ipregistry.api.client.exceptions.IpInfoException;
-import co.ipregistry.api.client.model.ConnectionType;
-import co.ipregistry.api.client.model.IpInfo;
-import co.ipregistry.api.client.model.IpInfoList;
-import co.ipregistry.api.client.model.IpType;
+import co.ipregistry.api.client.model.*;
 import co.ipregistry.api.client.options.IpregistryOptions;
 import com.google.common.collect.ImmutableList;
 import com.google.common.collect.Lists;
@@ -219,4 +216,22 @@ void testOriginLookup() throws ApiException, ClientException {
         Assertions.assertNotNull(ipInfo.getTimeZone());
     }
 
+    @Test
+    void testUserAgentParsing() throws ApiException, ClientException {
+        final IpregistryClient client = new IpregistryClient(apiKey);
+        final UserAgentList userAgentList =
+                client.parse(
+                        "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/102.0.5005.63 Safari/537.36",
+                        "Mozilla/5.0 (Windows NT 6.1; Win64; x64; rv:64.0) Gecko/20100101 Firefox/64.0",
+                        "@@@");
+
+        Assertions.assertEquals(3, userAgentList.size());
+        Assertions.assertEquals("Chrome", userAgentList.get(0).getName());
+        Assertions.assertEquals("Linux", userAgentList.get(0).getOperatingSystem().getName());
+        Assertions.assertEquals("Firefox", userAgentList.get(1).getName());
+        Assertions.assertEquals("Windows NT", userAgentList.get(1).getOperatingSystem().getName());
+        Assertions.assertEquals("Hacker", userAgentList.get(2).getName());
+        Assertions.assertEquals("Hacker", userAgentList.get(2).getOperatingSystem().getName());
+    }
+
 }

src/main/java/co/ipregistry/api/client/IpregistryClient.java

@@ -20,9 +20,8 @@
 import co.ipregistry.api.client.cache.NoCache;
 import co.ipregistry.api.client.exceptions.ApiException;
 import co.ipregistry.api.client.exceptions.ClientException;
-import co.ipregistry.api.client.model.IpInfo;
-import co.ipregistry.api.client.model.IpInfoList;
-import co.ipregistry.api.client.model.RequesterIpInfo;
+import co.ipregistry.api.client.exceptions.IpregistryException;
+import co.ipregistry.api.client.model.*;
 import co.ipregistry.api.client.options.IpregistryOption;
 import co.ipregistry.api.client.request.DefaultRequestHandler;
 
@@ -207,4 +206,8 @@ public IpInfoList lookup(final List<String> ips, final IpregistryOption... optio
         return new IpInfoList(result);
     }
 
+    public UserAgentList parse(final String... userAgents) throws ApiException, ClientException {
+        return requestHandler.parse(userAgents);
+    }
+
 }

src/main/java/co/ipregistry/api/client/exceptions/UserAgentException.java

@@ -0,0 +1,39 @@
+/*
+ * Copyright 2019 Ipregistry (https://ipregistry.co).
+ *
+ * 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 co.ipregistry.api.client.exceptions;
+
+import lombok.Getter;
+
+
+/**
+ * UserAgent exception.
+ */
+@Getter
+public class UserAgentException extends ApiException {
+
+    /**
+     * Creates a new instance with the specified arguments.
+     *
+     * @param errorCode the error code.
+     * @param message the message describing the error.
+     * @param resolution a sentence explaining how to resolve the error.
+     */
+    public UserAgentException(final String errorCode, final String message, final String resolution) {
+        super(errorCode, message, resolution);
+    }
+
+}

src/main/java/co/ipregistry/api/client/model/UserAgentList.java

@@ -16,17 +16,21 @@
 
 package co.ipregistry.api.client.model;
 
+import co.ipregistry.api.client.exceptions.UserAgentException;
 import com.fasterxml.jackson.annotation.JsonProperty;
+import com.fasterxml.jackson.databind.annotation.JsonDeserialize;
 import lombok.AllArgsConstructor;
 import lombok.Data;
 import lombok.NoArgsConstructor;
+import lombok.Setter;
 
 
 /**
  * A list of user-agent data as a result of a bulk parsing.
  */
 @AllArgsConstructor
-@Data
+@JsonDeserialize(using = UserAgentListDeserializer.class)
+@Setter
 @NoArgsConstructor
 public class UserAgentList {
 
@@ -53,4 +57,31 @@ public void set(final int index, final Object value) {
         userAgents[index] = value;
     }
 
+    public UserAgent get(final int index) throws UserAgentException {
+        final Object object = userAgents[index];
+
+        if (object instanceof UserAgent) {
+            return (UserAgent) object;
+        }
+
+        throw (UserAgentException) object;
+    }
+
+    /**
+     * Returns the list size.
+     *
+     * @return the number of entries available in the list.
+     */
+    public int size() {
+        if (userAgents == null) {
+            return 0;
+        }
+
+        return userAgents.length;
+    }
+
+    public Object unsafeGet(final int index) {
+        return userAgents[index];
+    }
+
 }

src/main/java/co/ipregistry/api/client/model/UserAgentListDeserializer.java

@@ -0,0 +1,67 @@
+/*
+ * Copyright 2022 Ipregistry (https://ipregistry.co).
+ *
+ * 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 co.ipregistry.api.client.model;
+
+import co.ipregistry.api.client.exceptions.IpInfoException;
+import co.ipregistry.api.client.model.error.LookupError;
+import com.fasterxml.jackson.core.JsonParser;
+import com.fasterxml.jackson.core.ObjectCodec;
+import com.fasterxml.jackson.core.TreeNode;
+import com.fasterxml.jackson.databind.DeserializationContext;
+import com.fasterxml.jackson.databind.JsonDeserializer;
+
+import java.io.IOException;
+
+
+/**
+ * Implementation used to deserialize an {@link UserAgentList}.
+ */
+public class UserAgentListDeserializer extends JsonDeserializer<Object> {
+
+    /**
+     * Creates a new instance.
+     */
+    public UserAgentListDeserializer() {
+        super();
+    }
+
+    @Override
+    public UserAgentList deserialize(final JsonParser parser, final DeserializationContext context) throws IOException {
+        final ObjectCodec codec = parser.getCodec();
+        final TreeNode treeNode = codec.readTree(parser).get("results");
+
+        final Object[] objects = new Object[treeNode.size()];
+
+        for (int i = 0; i < treeNode.size(); i++) {
+            final TreeNode userAgentOrLookupError = treeNode.get(i);
+
+            if (userAgentOrLookupError.get("code") == null) {
+                objects[i] = codec.treeToValue(userAgentOrLookupError, UserAgent.class);
+            } else {
+                final LookupError lookupError = codec.treeToValue(userAgentOrLookupError, LookupError.class);
+                objects[i] =
+                        new IpInfoException(
+                                lookupError.getCode(),
+                                lookupError.getMessage(),
+                                lookupError.getResolution());
+            }
+        }
+
+        return new UserAgentList(objects);
+    }
+
+}

src/main/java/co/ipregistry/api/client/request/DefaultRequestHandler.java

@@ -22,6 +22,7 @@
 import co.ipregistry.api.client.model.IpInfo;
 import co.ipregistry.api.client.model.IpInfoList;
 import co.ipregistry.api.client.model.RequesterIpInfo;
+import co.ipregistry.api.client.model.UserAgentList;
 import co.ipregistry.api.client.model.error.LookupError;
 import co.ipregistry.api.client.options.IpregistryOption;
 import com.fasterxml.jackson.databind.DeserializationFeature;
@@ -36,6 +37,8 @@
 import java.io.UnsupportedEncodingException;
 import java.net.URLEncoder;
 import java.nio.charset.StandardCharsets;
+import java.util.Arrays;
+import java.util.Iterator;
 import java.util.stream.Collectors;
 import java.util.stream.StreamSupport;
 
@@ -86,7 +89,7 @@ public IpInfo lookup(final String ip, final IpregistryOption... options) throws
         try {
             final Class<? extends IpInfo> type = "".equals(ip) || ip == null ? RequesterIpInfo.class : IpInfo.class;
 
-            final Object result = Request.get(buildApiUrl(ip, options))
+            final Object result = Request.get(buildIpLookupUrl(ip, options))
                     .addHeader("authorization", "ApiKey " + config.getApiKey())
                     .addHeader("user-agent", USER_AGENT)
                     .connectTimeout(Timeout.ofMilliseconds(config.getConnectionTimeout()))
@@ -131,13 +134,13 @@ private ApiException createCustomException(final ClassicHttpResponse response) t
     }
 
     /**
-     * Crafts a new API URL for the specified {@code ip} and {@code options}.
+     * Crafts a new URL for the specified {@code ip} and {@code options}.
      *
      * @param ip      the IP address to lookup.
      * @param options the options to pass.
      * @return an API URL for the specified input arguments.
      */
-    protected String buildApiUrl(final String ip, final IpregistryOption... options) {
+    protected String buildIpLookupUrl(final String ip, final IpregistryOption... options) {
         final StringBuilder result = new StringBuilder();
 
         result.append(config.getBaseUrl());
@@ -165,7 +168,7 @@ protected String buildApiUrl(final String ip, final IpregistryOption... options)
 
     public IpInfoList lookup(final Iterable<String> ips, final IpregistryOption... options) throws ApiException, ClientException {
         try {
-            final Object result = Request.post(buildApiUrl("", options))
+            final Object result = Request.post(buildIpLookupUrl("", options))
                     .bodyString(toJsonList(ips), ContentType.APPLICATION_JSON)
                     .addHeader("authorization", "ApiKey " + config.getApiKey())
                     .addHeader("user-agent", USER_AGENT)
@@ -193,6 +196,47 @@ public IpInfoList lookup(final Iterable<String> ips, final IpregistryOption... o
         }
     }
 
+    @Override
+    public UserAgentList parse(final String... userAgents) throws ApiException, ClientException {
+        final StringBuilder buffer = new StringBuilder();
+        final Iterator<String> iterator = Arrays.stream(userAgents).iterator();
+        while (iterator.hasNext()) {
+            buffer.append('"');
+            buffer.append(iterator.next());
+            buffer.append('"');
+            if (iterator.hasNext()) {
+                buffer.append(',');
+            }
+        }
+
+        try {
+            final Object result = Request.post(config.getBaseUrl() + "/user_agent")
+                    .bodyString("[" + buffer + "]", ContentType.APPLICATION_JSON)
+                    .addHeader("authorization", "ApiKey " + config.getApiKey())
+                    .connectTimeout(Timeout.ofMilliseconds(config.getConnectionTimeout()))
+                    .responseTimeout(Timeout.ofMilliseconds(config.getSocketTimeout()))
+                    .execute().handleResponse(response -> {
+                        try {
+                            if (response.getCode() == HttpStatus.SC_OK) {
+                                return objectMapper.readValue(response.getEntity().getContent(), UserAgentList.class);
+                            } else {
+                                return createCustomException(response);
+                            }
+                        } catch (final IOException e) {
+                            return new ClientException(e);
+                        }
+                    });
+
+            if (result instanceof UserAgentList) {
+                return (UserAgentList) result;
+            }
+
+            throw (ApiException) result;
+        } catch (final IOException e) {
+            throw new ClientException(e);
+        }
+    }
+
     private String toJsonList(final Iterable<String> ips) {
         return '[' + StreamSupport
                 .stream(ips.spliterator(), false)

src/main/java/co/ipregistry/api/client/request/IpregistryRequestHandler.java

@@ -16,9 +16,12 @@
 
 package co.ipregistry.api.client.request;
 
+import co.ipregistry.api.client.exceptions.ApiException;
+import co.ipregistry.api.client.exceptions.ClientException;
 import co.ipregistry.api.client.exceptions.IpregistryException;
 import co.ipregistry.api.client.model.IpInfo;
 import co.ipregistry.api.client.model.IpInfoList;
+import co.ipregistry.api.client.model.UserAgentList;
 import co.ipregistry.api.client.options.IpregistryOption;
 
 
@@ -55,4 +58,6 @@ public interface IpregistryRequestHandler {
      */
     IpInfoList lookup(Iterable<String> ips, IpregistryOption... options) throws IpregistryException;
 
+    UserAgentList parse(String... userAgents) throws ApiException, ClientException;
+
 }

src/test/java/co/ipregistry/api/client/request/DefaultRequestHandlerTest.java

@@ -30,7 +30,7 @@ void testBuildApiUrl_optionsEncoded() {
         final DefaultRequestHandler requestHandler =
                 new DefaultRequestHandler(config);
         final String url =
-                requestHandler.buildApiUrl(
+                requestHandler.buildIpLookupUrl(
                         "8.8.8.8", new IpregistryOption("test", "[test]"));
         Assertions.assertEquals(config.getBaseUrl() + "/8.8.8.8?test=%5Btest%5D", url);
     }