folly/Uri.h

   1 /*
   2  * Copyright 2017 Facebook, Inc.
   3  *
   4  * Licensed under the Apache License, Version 2.0 (the "License");
   5  * you may not use this file except in compliance with the License.
   6  * You may obtain a copy of the License at
   7  *
   8  *   http://www.apache.org/licenses/LICENSE-2.0
   9  *
  10  * Unless required by applicable law or agreed to in writing, software
  11  * distributed under the License is distributed on an "AS IS" BASIS,
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  13  * See the License for the specific language governing permissions and
  14  * limitations under the License.
  15  */
  16
  17 #pragma once
  18 #define FOLLY_URI_H_
  19
  20 #include <string>
  21 #include <vector>
  22
  23 #include <folly/String.h>
  24
  25 namespace folly {
  26
  27 /**
  28  * Class representing a URI.
  29  *
  30  * Consider http://www.facebook.com/foo/bar?key=foo#anchor
  31  *
  32  * The URI is broken down into its parts: scheme ("http"), authority
  33  * (ie. host and port, in most cases: "www.facebook.com"), path
  34  * ("/foo/bar"), query ("key=foo") and fragment ("anchor").  The scheme is
  35  * lower-cased.
  36  *
  37  * If this Uri represents a URL, note that, to prevent ambiguity, the component
  38  * parts are NOT percent-decoded; you should do this yourself with
  39  * uriUnescape() (for the authority and path) and uriUnescape(...,
  40  * UriEscapeMode::QUERY) (for the query, but probably only after splitting at
  41  * '&' to identify the individual parameters).
  42  */
  43 class Uri {
  44  public:
  45   /**
  46    * Parse a Uri from a string.  Throws std::invalid_argument on parse error.
  47    */
  48   explicit Uri(StringPiece str);
  49
  50   const std::string& scheme() const { return scheme_; }
  51   const std::string& username() const { return username_; }
  52   const std::string& password() const { return password_; }
  53   /**
  54    * Get host part of URI. If host is an IPv6 address, square brackets will be
  55    * returned, for example: "[::1]".
  56    */
  57   const std::string& host() const { return host_; }
  58   /**
  59    * Get host part of URI. If host is an IPv6 address, square brackets will not
  60    * be returned, for exmaple "::1"; otherwise it returns the same thing as
  61    * host().
  62    *
  63    * hostname() is what one needs to call if passing the host to any other tool
  64    * or API that connects to that host/port; e.g. getaddrinfo() only understands
  65    * IPv6 host without square brackets
  66    */
  67   std::string hostname() const;
  68   uint16_t port() const { return port_; }
  69   const std::string& path() const { return path_; }
  70   const std::string& query() const { return query_; }
  71   const std::string& fragment() const { return fragment_; }
  72
  73   std::string authority() const;
  74
  75   template <class String>
  76   String toString() const;
  77
  78   std::string str() const { return toString<std::string>(); }
  79   fbstring fbstr() const { return toString<fbstring>(); }
  80
  81   void setPort(uint16_t port) {
  82     hasAuthority_ = true;
  83     port_ = port;
  84   }
  85
  86   /**
  87    * Get query parameters as key-value pairs.
  88    * e.g. for URI containing query string:  key1=foo&key2=&key3&=bar&=bar=
  89    * In returned list, there are 3 entries:
  90    *     "key1" => "foo"
  91    *     "key2" => ""
  92    *     "key3" => ""
  93    * Parts "=bar" and "=bar=" are ignored, as they are not valid query
  94    * parameters. "=bar" is missing parameter name, while "=bar=" has more than
  95    * one equal signs, we don't know which one is the delimiter for key and
  96    * value.
  97    *
  98    * Note, this method is not thread safe, it might update internal state, but
  99    * only the first call to this method update the state. After the first call
 100    * is finished, subsequent calls to this method are thread safe.
 101    *
 102    * @return  query parameter key-value pairs in a vector, each element is a
 103    *          pair of which the first element is parameter name and the second
 104    *          one is parameter value
 105    */
 106   const std::vector<std::pair<std::string, std::string>>& getQueryParams();
 107
 108  private:
 109   std::string scheme_;
 110   std::string username_;
 111   std::string password_;
 112   std::string host_;
 113   bool hasAuthority_;
 114   uint16_t port_;
 115   std::string path_;
 116   std::string query_;
 117   std::string fragment_;
 118   std::vector<std::pair<std::string, std::string>> queryParams_;
 119 };
 120
 121 } // namespace folly
 122
 123 #include <folly/Uri-inl.h>