git.basschouten.com Git - openhab-addons.git/blob

   1 /**
   2  * Copyright (c) 2010-2023 Contributors to the openHAB project
   3  *
   4  * See the NOTICE file(s) distributed with this work for additional
   5  * information.
   6  *
   7  * This program and the accompanying materials are made available under the
   8  * terms of the Eclipse Public License 2.0 which is available at
   9  * http://www.eclipse.org/legal/epl-2.0
  10  *
  11  * SPDX-License-Identifier: EPL-2.0
  12  */
  13 package org.openhab.binding.bticinosmarther.internal.api;
  14
  15 import static org.eclipse.jetty.http.HttpStatus.*;
  16
  17 import java.util.concurrent.CompletableFuture;
  18 import java.util.concurrent.ExecutionException;
  19 import java.util.concurrent.ScheduledExecutorService;
  20 import java.util.concurrent.TimeUnit;
  21 import java.util.concurrent.TimeoutException;
  22 import java.util.function.Function;
  23
  24 import org.eclipse.jdt.annotation.NonNullByDefault;
  25 import org.eclipse.jetty.client.HttpClient;
  26 import org.eclipse.jetty.client.api.ContentResponse;
  27 import org.eclipse.jetty.client.api.Request;
  28 import org.eclipse.jetty.http.HttpStatus;
  29 import org.openhab.binding.bticinosmarther.internal.api.exception.SmartherAuthorizationException;
  30 import org.openhab.binding.bticinosmarther.internal.api.exception.SmartherGatewayException;
  31 import org.openhab.binding.bticinosmarther.internal.api.exception.SmartherInvalidResponseException;
  32 import org.openhab.binding.bticinosmarther.internal.api.exception.SmartherSubscriptionAlreadyExistsException;
  33 import org.openhab.binding.bticinosmarther.internal.api.exception.SmartherTokenExpiredException;
  34 import org.slf4j.Logger;
  35 import org.slf4j.LoggerFactory;
  36
  37 import com.google.gson.JsonElement;
  38 import com.google.gson.JsonObject;
  39 import com.google.gson.JsonParser;
  40 import com.google.gson.JsonSyntaxException;
  41
  42 /**
  43  * The {@code SmartherApiConnector} class is used to perform the actual call to the API gateway.
  44  * It handles the returned http status codes and the error codes eventually returned by the API gateway itself.
  45  *
  46  * Response mappings:
  47  * <ul>
  48  * <li>Plants : 200, 204, 400, 401, 404, 408, 469, 470, 500</li>
  49  * <li>Topology : 200, 400, 401, 404, 408, 469, 470, 500</li>
  50  * <li>Measures : 200, 400, 401, 404, 408, 469, 470, 500</li>
  51  * <li>ProgramList : 200, 400, 401, 404, 408, 469, 470, 500</li>
  52  * <li>Get Status : 200, 400, 401, 404, 408, 469, 470, 500</li>
  53  * <li>Set Status : 200, 400, 401, 404, 408, 430, 469, 470, 486, 500</li>
  54  * <li>Get Subscriptions : 200, 204, 400, 401, 404, 500</li>
  55  * <li>Subscribe : 201, 400, 401, 404, 409, 500</li>
  56  * <li>Delete Subscription : 200, 400, 401, 404, 500</li>
  57  * </ul>
  58  *
  59  * @author Fabio Possieri - Initial contribution
  60  */
  61 @NonNullByDefault
  62 public class SmartherApiConnector {
  63
  64     private static final String RETRY_AFTER_HEADER = "Retry-After";
  65     private static final String AUTHORIZATION_HEADER = "Authorization";
  66     private static final String SUBSCRIPTION_HEADER = "Ocp-Apim-Subscription-Key";
  67
  68     private static final String ERROR_CODE = "statusCode";
  69     private static final String ERROR_MESSAGE = "message";
  70     private static final String TOKEN_EXPIRED = "expired";
  71     private static final String AUTHORIZATION_ERROR = "error_description";
  72
  73     private static final int HTTP_CLIENT_TIMEOUT_SECONDS = 10;
  74     private static final int HTTP_CLIENT_RETRY_COUNT = 5;
  75
  76     // Set Chronothermostat Status > Wrong input parameters
  77     private static final int WRONG_INPUT_PARAMS_430 = 430;
  78     // Official application password expired: password used in the Thermostat official app is expired.
  79     private static final int APP_PASSWORD_EXPIRED_469 = 469;
  80     // Official application terms and conditions expired: terms and conditions for Thermostat official app are expired.
  81     private static final int APP_TERMS_EXPIRED_470 = 470;
  82     // Set Chronothermostat Status > Busy visual user interface
  83     private static final int BUSY_VISUAL_UI_486 = 486;
  84
  85     private final Logger logger = LoggerFactory.getLogger(SmartherApiConnector.class);
  86
  87     private final HttpClient httpClient;
  88     private final ScheduledExecutorService scheduler;
  89
  90     /**
  91      * Constructs a {@code SmartherApiConnector} to the API gateway with the specified scheduler and http client.
  92      *
  93      * @param scheduler
  94      *            the scheduler to be used to reschedule calls when rate limit exceeded or call not succeeded
  95      * @param httpClient
  96      *            the http client to be used to make http calls to the API gateway
  97      */
  98     public SmartherApiConnector(ScheduledExecutorService scheduler, HttpClient httpClient) {
  99         this.scheduler = scheduler;
 100         this.httpClient = httpClient;
 101     }
 102
 103     /**
 104      * Performs a call to the API gateway and returns the raw response.
 105      *
 106      * @param requester
 107      *            the function to construct the request, using the http client that is passed as argument to the
 108      *            function itself
 109      * @param subscription
 110      *            the subscription string to be used in the call {@code Subscription} header
 111      * @param authorization
 112      *            the authorization string to be used in the call {@code Authorization} header
 113      *
 114      * @return the raw response returned by the API gateway
 115      *
 116      * @throws SmartherGatewayException if the call failed due to an issue with the API gateway
 117      */
 118     public ContentResponse request(Function<HttpClient, Request> requester, String subscription, String authorization)
 119             throws SmartherGatewayException {
 120         final Caller caller = new Caller(requester, subscription, authorization);
 121
 122         try {
 123             return caller.call().get();
 124         } catch (InterruptedException e) {
 125             Thread.currentThread().interrupt();
 126             throw new SmartherGatewayException("Thread interrupted");
 127         } catch (ExecutionException e) {
 128             final Throwable cause = e.getCause();
 129
 130             if (cause instanceof SmartherGatewayException gatewayException) {
 131                 throw gatewayException;
 132             } else {
 133                 throw new SmartherGatewayException(e.getMessage(), e);
 134             }
 135         }
 136     }
 137
 138     /**
 139      * The {@code Caller} class represents the handler to make calls to the API gateway.
 140      * In case of rate limiting or not finished jobs, it will retry a number of times in a specified timeframe then
 141      * gives up with an exception.
 142      *
 143      * @author Fabio Possieri - Initial contribution
 144      */
 145     private class Caller {
 146         private final Function<HttpClient, Request> requester;
 147         private final String subscription;
 148         private final String authorization;
 149
 150         private final CompletableFuture<ContentResponse> future = new CompletableFuture<>();
 151         private int delaySeconds;
 152         private int attempts;
 153
 154         /**
 155          * Constructs a {@code Caller} to the API gateway with the specified requester, subscription and authorization.
 156          *
 157          * @param requester
 158          *            the function to construct the request, using the http client that is passed as argument to the
 159          *            function itself
 160          * @param subscription
 161          *            the subscription string to be used in the call {@code Subscription} header
 162          * @param authorization
 163          *            the authorization string to be used in the call {@code Authorization} header
 164          */
 165         public Caller(Function<HttpClient, Request> requester, String subscription, String authorization) {
 166             this.requester = requester;
 167             this.subscription = subscription;
 168             this.authorization = authorization;
 169         }
 170
 171         /**
 172          * Performs the request as a {@link CompletableFuture}, setting its state once finished.
 173          * The original caller should call the {@code get} method on the Future to wait for the call to finish.
 174          * The first attempt is not scheduled so, if the first call succeeds, the {@code get} method directly returns
 175          * the value. This method is rescheduled in case the call is to be retried.
 176          *
 177          * @return the {@link CompletableFuture} holding the call
 178          */
 179         public CompletableFuture<ContentResponse> call() {
 180             attempts++;
 181             try {
 182                 final boolean success = processResponse(requester.apply(httpClient)
 183                         .header(SUBSCRIPTION_HEADER, subscription).header(AUTHORIZATION_HEADER, authorization)
 184                         .timeout(HTTP_CLIENT_TIMEOUT_SECONDS, TimeUnit.SECONDS).send());
 185
 186                 if (!success) {
 187                     if (attempts < HTTP_CLIENT_RETRY_COUNT) {
 188                         logger.debug("API Gateway call attempt: {}", attempts);
 189
 190                         scheduler.schedule(this::call, delaySeconds, TimeUnit.SECONDS);
 191                     } else {
 192                         logger.debug("Giving up on accessing API Gateway. Check network connectivity!");
 193                         future.completeExceptionally(new SmartherGatewayException(
 194                                 String.format("Could not reach the API Gateway after %s retries.", attempts)));
 195                     }
 196                 }
 197             } catch (ExecutionException e) {
 198                 Throwable cause = e.getCause();
 199                 future.completeExceptionally(cause != null ? cause : e);
 200             } catch (SmartherGatewayException e) {
 201                 future.completeExceptionally(e);
 202             } catch (RuntimeException | TimeoutException e) {
 203                 future.completeExceptionally(e);
 204             } catch (InterruptedException e) {
 205                 Thread.currentThread().interrupt();
 206                 future.completeExceptionally(e);
 207             }
 208             return future;
 209         }
 210
 211         /**
 212          * Processes the response from the API gateway call and handles the http status codes.
 213          *
 214          * @param response
 215          *            the response content returned by the API gateway
 216          *
 217          * @return {@code true} if the call was successful, {@code false} if the call failed in a way that can be
 218          *         retried
 219          *
 220          * @throws {@link SmartherGatewayException}
 221          *             if the call failed due to an irrecoverable issue and cannot be retried (user should be informed)
 222          */
 223         private boolean processResponse(ContentResponse response) throws SmartherGatewayException {
 224             boolean success = false;
 225
 226             logger.debug("Response Code: {}", response.getStatus());
 227             if (logger.isTraceEnabled()) {
 228                 logger.trace("Response Data: {}", response.getContentAsString());
 229             }
 230             switch (response.getStatus()) {
 231                 case OK_200:
 232                 case CREATED_201:
 233                 case NO_CONTENT_204:
 234                 case NOT_MODIFIED_304:
 235                     future.complete(response);
 236                     success = true;
 237                     break;
 238
 239                 case ACCEPTED_202:
 240                     logger.debug(
 241                             "API Gateway returned error status 202 (the request has been accepted for processing, but the processing has not been completed)");
 242                     future.complete(response);
 243                     success = true;
 244                     break;
 245
 246                 case FORBIDDEN_403:
 247                     // Process for authorization error, and logging.
 248                     processErrorState(response);
 249                     future.complete(response);
 250                     success = true;
 251                     break;
 252
 253                 case BAD_REQUEST_400:
 254                 case NOT_FOUND_404:
 255                 case REQUEST_TIMEOUT_408:
 256                 case WRONG_INPUT_PARAMS_430:
 257                 case APP_PASSWORD_EXPIRED_469:
 258                 case APP_TERMS_EXPIRED_470:
 259                 case BUSY_VISUAL_UI_486:
 260                 case INTERNAL_SERVER_ERROR_500:
 261                     throw new SmartherGatewayException(processErrorState(response));
 262
 263                 case UNAUTHORIZED_401:
 264                     throw new SmartherAuthorizationException(processErrorState(response));
 265
 266                 case CONFLICT_409:
 267                     // Subscribe to C2C notifications > Subscription already exists.
 268                     throw new SmartherSubscriptionAlreadyExistsException(processErrorState(response));
 269
 270                 case TOO_MANY_REQUESTS_429:
 271                     // Response Code 429 means requests rate limits exceeded.
 272                     final String retryAfter = response.getHeaders().get(RETRY_AFTER_HEADER);
 273                     logger.debug(
 274                             "API Gateway returned error status 429 (rate limit exceeded - retry after {} seconds, decrease polling interval of bridge, going to sleep...)",
 275                             retryAfter);
 276                     delaySeconds = Integer.parseInt(retryAfter);
 277                     break;
 278
 279                 case BAD_GATEWAY_502:
 280                 case SERVICE_UNAVAILABLE_503:
 281                 default:
 282                     throw new SmartherGatewayException(String.format("API Gateway returned error status %s (%s)",
 283                             response.getStatus(), HttpStatus.getMessage(response.getStatus())));
 284             }
 285             return success;
 286         }
 287
 288         /**
 289          * Processes the responded content if the status code indicated an error.
 290          *
 291          * @param response
 292          *            the response content returned by the API gateway
 293          *
 294          * @return the error message extracted from the response content
 295          *
 296          * @throws {@link SmartherTokenExpiredException}
 297          *             if the authorization access token used to communicate with the API gateway has expired
 298          * @throws {@link SmartherAuthorizationException}
 299          *             if a generic authorization issue with the API gateway has occurred
 300          * @throws {@link SmartherInvalidResponseException}
 301          *             if the response received from the API gateway cannot be parsed
 302          */
 303         private String processErrorState(ContentResponse response)
 304                 throws SmartherTokenExpiredException, SmartherAuthorizationException, SmartherInvalidResponseException {
 305             try {
 306                 final JsonElement element = JsonParser.parseString(response.getContentAsString());
 307
 308                 if (element.isJsonObject()) {
 309                     final JsonObject object = element.getAsJsonObject();
 310                     if (object.has(ERROR_CODE) && object.has(ERROR_MESSAGE)) {
 311                         final String message = object.get(ERROR_MESSAGE).getAsString();
 312
 313                         // Bad request can be anything, from authorization problems to plant or module problems.
 314                         // Therefore authorization type errors are filtered and handled differently.
 315                         logger.debug("Bad request: {}", message);
 316                         if (message.contains(TOKEN_EXPIRED)) {
 317                             throw new SmartherTokenExpiredException(message);
 318                         } else {
 319                             return message;
 320                         }
 321                     } else if (object.has(AUTHORIZATION_ERROR)) {
 322                         final String errorDescription = object.get(AUTHORIZATION_ERROR).getAsString();
 323                         throw new SmartherAuthorizationException(errorDescription);
 324                     }
 325                 }
 326                 logger.debug("Unknown response: {}", response);
 327                 return "Unknown response";
 328             } catch (JsonSyntaxException e) {
 329                 logger.warn("Response was not json: ", e);
 330                 throw new SmartherInvalidResponseException(e.getMessage());
 331             }
 332         }
 333     }
 334 }