folly/SocketAddress.h

   1 /*
   2  * Copyright 2016 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
  19 #include <sys/types.h>
  20 #include <sys/socket.h>
  21 #include <sys/un.h>
  22 #include <netinet/in.h>
  23 #include <netdb.h>
  24 #include <cstddef>
  25 #include <iostream>
  26 #include <string>
  27
  28 #include <folly/IPAddress.h>
  29 #include <folly/Portability.h>
  30 #include <folly/Range.h>
  31
  32 namespace folly {
  33
  34 class SocketAddress {
  35  public:
  36   SocketAddress() = default;
  37
  38   /**
  39    * Construct a SocketAddress from a hostname and port.
  40    *
  41    * Note: If the host parameter is not a numeric IP address, hostname
  42    * resolution will be performed, which can be quite slow.
  43    *
  44    * Raises std::system_error on error.
  45    *
  46    * @param host The IP address (or hostname, if allowNameLookup is true)
  47    * @param port The port (in host byte order)
  48    * @pram allowNameLookup  If true, attempt to perform hostname lookup
  49    *        if the hostname does not appear to be a numeric IP address.
  50    *        This is potentially a very slow operation, so is disabled by
  51    *        default.
  52    */
  53   SocketAddress(const char* host, uint16_t port,
  54                  bool allowNameLookup = false) {
  55     // Initialize the address family first,
  56     // since setFromHostPort() and setFromIpPort() will check it.
  57
  58     if (allowNameLookup) {
  59       setFromHostPort(host, port);
  60     } else {
  61       setFromIpPort(host, port);
  62     }
  63   }
  64
  65   SocketAddress(const std::string& host, uint16_t port,
  66                  bool allowNameLookup = false) {
  67     // Initialize the address family first,
  68     // since setFromHostPort() and setFromIpPort() will check it.
  69
  70     if (allowNameLookup) {
  71       setFromHostPort(host.c_str(), port);
  72     } else {
  73       setFromIpPort(host.c_str(), port);
  74     }
  75   }
  76
  77   SocketAddress(const IPAddress& ipAddr, uint16_t port) {
  78     setFromIpAddrPort(ipAddr, port);
  79   }
  80
  81   SocketAddress(const SocketAddress& addr) {
  82     port_ = addr.port_;
  83     if (addr.getFamily() == AF_UNIX) {
  84       storage_.un.init(addr.storage_.un);
  85     } else {
  86       storage_ = addr.storage_;
  87     }
  88     external_ = addr.external_;
  89   }
  90
  91   SocketAddress& operator=(const SocketAddress& addr) {
  92     if (!external_) {
  93       if (addr.getFamily() != AF_UNIX) {
  94         storage_ = addr.storage_;
  95       } else {
  96         storage_ = addr.storage_;
  97         storage_.un.init(addr.storage_.un);
  98       }
  99     } else {
 100       if (addr.getFamily() == AF_UNIX) {
 101         storage_.un.copy(addr.storage_.un);
 102       } else {
 103         storage_.un.free();
 104         storage_ = addr.storage_;
 105       }
 106     }
 107     port_ = addr.port_;
 108     external_ = addr.external_;
 109     return *this;
 110   }
 111
 112   SocketAddress(SocketAddress&& addr) noexcept {
 113     storage_ = addr.storage_;
 114     port_ = addr.port_;
 115     external_ = addr.external_;
 116     addr.external_ = false;
 117   }
 118
 119   SocketAddress& operator=(SocketAddress&& addr) {
 120     std::swap(storage_, addr.storage_);
 121     std::swap(port_, addr.port_);
 122     std::swap(external_, addr.external_);
 123     return *this;
 124   }
 125
 126   ~SocketAddress() {
 127     if (external_) {
 128       storage_.un.free();
 129     }
 130   }
 131
 132   bool isInitialized() const {
 133     return (getFamily() != AF_UNSPEC);
 134   }
 135
 136   /**
 137    * Return whether this address is within private network.
 138    *
 139    * According to RFC1918, the 10/8 prefix, 172.16/12 prefix, and 192.168/16
 140    * prefix are reserved for private networks.
 141    * fc00::/7 is the IPv6 version, defined in RFC4139.  IPv6 link-local
 142    * addresses (fe80::/10) are also considered private addresses.
 143    *
 144    * The loopback addresses 127/8 and ::1 are also regarded as private networks
 145    * for the purpose of this function.
 146    *
 147    * Returns true if this is a private network address, and false otherwise.
 148    */
 149   bool isPrivateAddress() const;
 150
 151   /**
 152    * Return whether this address is a loopback address.
 153    */
 154   bool isLoopbackAddress() const;
 155
 156   void reset() {
 157     prepFamilyChange(AF_UNSPEC);
 158   }
 159
 160   /**
 161    * Initialize this SocketAddress from a hostname and port.
 162    *
 163    * Note: If the host parameter is not a numeric IP address, hostname
 164    * resolution will be performed, which can be quite slow.
 165    *
 166    * If the hostname resolves to multiple addresses, only the first will be
 167    * returned.
 168    *
 169    * Raises std::system_error on error.
 170    *
 171    * @param host The hostname or IP address
 172    * @param port The port (in host byte order)
 173    */
 174   void setFromHostPort(const char* host, uint16_t port);
 175
 176   void setFromHostPort(const std::string& host, uint16_t port) {
 177     setFromHostPort(host.c_str(), port);
 178   }
 179
 180   /**
 181    * Initialize this SocketAddress from an IP address and port.
 182    *
 183    * This is similar to setFromHostPort(), but only accepts numeric IP
 184    * addresses.  If the IP string does not look like an IP address, it throws a
 185    * std::invalid_argument rather than trying to perform a hostname resolution.
 186    *
 187    * Raises std::system_error on error.
 188    *
 189    * @param ip The IP address, as a human-readable string.
 190    * @param port The port (in host byte order)
 191    */
 192   void setFromIpPort(const char* ip, uint16_t port);
 193
 194   void setFromIpPort(const std::string& ip, uint16_t port) {
 195     setFromIpPort(ip.c_str(), port);
 196   }
 197
 198   /**
 199    * Initialize this SocketAddress from an IPAddress struct and port.
 200    *
 201    * @param ip The IP address in IPAddress format
 202    * @param port The port (in host byte order)
 203    */
 204   void setFromIpAddrPort(const IPAddress& ip, uint16_t port);
 205
 206   /**
 207    * Initialize this SocketAddress from a local port number.
 208    *
 209    * This is intended to be used by server code to determine the address to
 210    * listen on.
 211    *
 212    * If the current machine has any IPv6 addresses configured, an IPv6 address
 213    * will be returned (since connections from IPv4 clients can be mapped to the
 214    * IPv6 address).  If the machine does not have any IPv6 addresses, an IPv4
 215    * address will be returned.
 216    */
 217   void setFromLocalPort(uint16_t port);
 218
 219   /**
 220    * Initialize this SocketAddress from a local port number.
 221    *
 222    * This version of setFromLocalPort() accepts the port as a string.  A
 223    * std::invalid_argument will be raised if the string does not refer to a port
 224    * number.  Non-numeric service port names are not accepted.
 225    */
 226   void setFromLocalPort(const char* port);
 227   void setFromLocalPort(const std::string& port) {
 228     return setFromLocalPort(port.c_str());
 229   }
 230
 231   /**
 232    * Initialize this SocketAddress from a local port number and optional IP
 233    * address.
 234    *
 235    * The addressAndPort string may be specified either as "<ip>:<port>", or
 236    * just as "<port>".  If the IP is not specified, the address will be
 237    * initialized to 0, so that a server socket bound to this address will
 238    * accept connections on all local IP addresses.
 239    *
 240    * Both the IP address and port number must be numeric.  DNS host names and
 241    * non-numeric service port names are not accepted.
 242    */
 243   void setFromLocalIpPort(const char* addressAndPort);
 244   void setFromLocalIpPort(const std::string& addressAndPort) {
 245     return setFromLocalIpPort(addressAndPort.c_str());
 246   }
 247
 248   /**
 249    * Initialize this SocketAddress from an IP address and port number.
 250    *
 251    * The addressAndPort string must be of the form "<ip>:<port>".  E.g.,
 252    * "10.0.0.1:1234".
 253    *
 254    * Both the IP address and port number must be numeric.  DNS host names and
 255    * non-numeric service port names are not accepted.
 256    */
 257   void setFromIpPort(const char* addressAndPort);
 258   void setFromIpPort(const std::string& addressAndPort) {
 259     return setFromIpPort(addressAndPort.c_str());
 260   }
 261
 262   /**
 263    * Initialize this SocketAddress from a host name and port number.
 264    *
 265    * The addressAndPort string must be of the form "<host>:<port>".  E.g.,
 266    * "www.facebook.com:443".
 267    *
 268    * If the host name is not a numeric IP address, a DNS lookup will be
 269    * performed.  Beware that the DNS lookup may be very slow.  The port number
 270    * must be numeric; non-numeric service port names are not accepted.
 271    */
 272   void setFromHostPort(const char* hostAndPort);
 273   void setFromHostPort(const std::string& hostAndPort) {
 274     return setFromHostPort(hostAndPort.c_str());
 275   }
 276
 277   /**
 278    * Initialize this SocketAddress from a local unix path.
 279    *
 280    * Raises std::invalid_argument on error.
 281    */
 282   void setFromPath(StringPiece path);
 283
 284   void setFromPath(const char* path, size_t length) {
 285     setFromPath(StringPiece{path, length});
 286   }
 287
 288   // a typedef that allow us to compile against both winsock & POSIX sockets:
 289   using SocketDesc = decltype(socket(0,0,0)); // POSIX: int, winsock: unsigned
 290
 291   /**
 292    * Initialize this SocketAddress from a socket's peer address.
 293    *
 294    * Raises std::system_error on error.
 295    */
 296   void setFromPeerAddress(SocketDesc socket);
 297
 298   /**
 299    * Initialize this SocketAddress from a socket's local address.
 300    *
 301    * Raises std::system_error on error.
 302    */
 303   void setFromLocalAddress(SocketDesc socket);
 304
 305   /**
 306    * Initialize this folly::SocketAddress from a struct sockaddr.
 307    *
 308    * Raises std::system_error on error.
 309    *
 310    * This method is not supported for AF_UNIX addresses.  For unix addresses,
 311    * the address length must be explicitly specified.
 312    *
 313    * @param address  A struct sockaddr.  The size of the address is implied
 314    *                 from address->sa_family.
 315    */
 316   void setFromSockaddr(const struct sockaddr* address);
 317
 318   /**
 319    * Initialize this SocketAddress from a struct sockaddr.
 320    *
 321    * Raises std::system_error on error.
 322    *
 323    * @param address  A struct sockaddr.
 324    * @param addrlen  The length of address data available.  This must be long
 325    *                 enough for the full address type required by
 326    *                 address->sa_family.
 327    */
 328   void setFromSockaddr(const struct sockaddr* address,
 329                        socklen_t addrlen);
 330
 331   /**
 332    * Initialize this SocketAddress from a struct sockaddr_in.
 333    */
 334   void setFromSockaddr(const struct sockaddr_in* address);
 335
 336   /**
 337    * Initialize this SocketAddress from a struct sockaddr_in6.
 338    */
 339   void setFromSockaddr(const struct sockaddr_in6* address);
 340
 341   /**
 342    * Initialize this SocketAddress from a struct sockaddr_un.
 343    *
 344    * Note that the addrlen parameter is necessary to properly detect anonymous
 345    * addresses, which have 0 valid path bytes, and may not even have a NUL
 346    * character at the start of the path.
 347    *
 348    * @param address  A struct sockaddr_un.
 349    * @param addrlen  The length of address data.  This should include all of
 350    *                 the valid bytes of sun_path, not including any NUL
 351    *                 terminator.
 352    */
 353   void setFromSockaddr(const struct sockaddr_un* address,
 354                        socklen_t addrlen);
 355
 356
 357   /**
 358    * Fill in a given sockaddr_storage with the ip or unix address.
 359    *
 360    * Returns the actual size of the storage used.
 361    */
 362   socklen_t getAddress(sockaddr_storage* addr) const {
 363     if (!external_) {
 364       return storage_.addr.toSockaddrStorage(addr, htons(port_));
 365     } else {
 366       memcpy(addr, storage_.un.addr, sizeof(*storage_.un.addr));
 367       return storage_.un.len;
 368     }
 369   }
 370
 371   const folly::IPAddress& getIPAddress() const;
 372
 373   // Deprecated: getAddress() above returns the same size as getActualSize()
 374   socklen_t getActualSize() const;
 375
 376   sa_family_t getFamily() const {
 377     DCHECK(external_ || AF_UNIX != storage_.addr.family());
 378     return external_ ? AF_UNIX : storage_.addr.family();
 379   }
 380
 381   bool empty() const {
 382     return getFamily() == AF_UNSPEC;
 383   }
 384
 385   /**
 386    * Get a string representation of the IPv4 or IPv6 address.
 387    *
 388    * Raises std::invalid_argument if an error occurs (for example, if
 389    * the address is not an IPv4 or IPv6 address).
 390    */
 391   std::string getAddressStr() const;
 392
 393   /**
 394    * Get a string representation of the IPv4 or IPv6 address.
 395    *
 396    * Raises std::invalid_argument if an error occurs (for example, if
 397    * the address is not an IPv4 or IPv6 address).
 398    */
 399   void getAddressStr(char* buf, size_t buflen) const;
 400
 401   /**
 402    * For v4 & v6 addresses, return the fully qualified address string
 403    */
 404   std::string getFullyQualified() const;
 405
 406   /**
 407    * Get the IPv4 or IPv6 port for this address.
 408    *
 409    * Raises std::invalid_argument if this is not an IPv4 or IPv6 address.
 410    *
 411    * @return Returns the port, in host byte order.
 412    */
 413   uint16_t getPort() const;
 414
 415   /**
 416    * Set the IPv4 or IPv6 port for this address.
 417    *
 418    * Raises std::invalid_argument if this is not an IPv4 or IPv6 address.
 419    */
 420   void setPort(uint16_t port);
 421
 422   /**
 423    * Return true if this is an IPv4-mapped IPv6 address.
 424    */
 425   bool isIPv4Mapped() const {
 426     return (getFamily() == AF_INET6 &&
 427             storage_.addr.isIPv4Mapped());
 428   }
 429
 430   /**
 431    * Convert an IPv4-mapped IPv6 address to an IPv4 address.
 432    *
 433    * Raises std::invalid_argument if this is not an IPv4-mapped IPv6 address.
 434    */
 435   void convertToIPv4();
 436
 437   /**
 438    * Try to convert an address to IPv4.
 439    *
 440    * This attempts to convert an address to an IPv4 address if possible.
 441    * If the address is an IPv4-mapped IPv6 address, it is converted to an IPv4
 442    * address and true is returned.  Otherwise nothing is done, and false is
 443    * returned.
 444    */
 445   bool tryConvertToIPv4();
 446
 447   /**
 448    * Convert an IPv4 address to IPv6 [::ffff:a.b.c.d]
 449    */
 450
 451   bool mapToIPv6();
 452
 453   /**
 454    * Get string representation of the host name (or IP address if the host name
 455    * cannot be resolved).
 456    *
 457    * Warning: Using this method is strongly discouraged.  It performs a
 458    * DNS lookup, which may block for many seconds.
 459    *
 460    * Raises std::invalid_argument if an error occurs.
 461    */
 462   std::string getHostStr() const;
 463
 464   /**
 465    * Get the path name for a Unix domain socket.
 466    *
 467    * Returns a std::string containing the path.  For anonymous sockets, an
 468    * empty string is returned.
 469    *
 470    * For addresses in the abstract namespace (Linux-specific), a std::string
 471    * containing binary data is returned.  In this case the first character will
 472    * always be a NUL character.
 473    *
 474    * Raises std::invalid_argument if called on a non-Unix domain socket.
 475    */
 476   std::string getPath() const;
 477
 478   /**
 479    * Get human-readable string representation of the address.
 480    *
 481    * This prints a string representation of the address, for human consumption.
 482    * For IP addresses, the string is of the form "<IP>:<port>".
 483    */
 484   std::string describe() const;
 485
 486   bool operator==(const SocketAddress& other) const;
 487   bool operator!=(const SocketAddress& other) const {
 488     return !(*this == other);
 489   }
 490
 491   /**
 492    * Check whether the first N bits of this address match the first N
 493    * bits of another address.
 494    * @note returns false if the addresses are not from the same
 495    *       address family or if the family is neither IPv4 nor IPv6
 496    */
 497   bool prefixMatch(const SocketAddress& other, unsigned prefixLength) const;
 498
 499   /**
 500    * Use this operator for storing maps based on SocketAddress.
 501    */
 502   bool operator<(const SocketAddress& other) const;
 503
 504   /**
 505    * Compuate a hash of a SocketAddress.
 506    */
 507   size_t hash() const;
 508
 509  private:
 510   /**
 511    * Unix socket addresses require more storage than IPv4 and IPv6 addresses,
 512    * and are comparatively little-used.
 513    *
 514    * Therefore SocketAddress' internal storage_ member variable doesn't
 515    * contain room for a full unix address, to avoid wasting space in the common
 516    * case.  When we do need to store a Unix socket address, we use this
 517    * ExternalUnixAddr structure to allocate a struct sockaddr_un separately on
 518    * the heap.
 519    */
 520   struct ExternalUnixAddr {
 521     struct sockaddr_un *addr;
 522     socklen_t len;
 523
 524     /* For debugging only, will be removed */
 525     uint64_t magic;
 526     static constexpr uint64_t kMagic = 0x1234faceb00c;
 527
 528     socklen_t pathLength() const {
 529       return len - offsetof(struct sockaddr_un, sun_path);
 530     }
 531
 532     void init() {
 533       addr = new sockaddr_un;
 534       magic = kMagic;
 535       addr->sun_family = AF_UNIX;
 536       len = 0;
 537     }
 538     void init(const ExternalUnixAddr &other) {
 539       addr = new sockaddr_un;
 540       magic = kMagic;
 541       len = other.len;
 542       memcpy(addr, other.addr, len);
 543       // Fill the rest with 0s, just for safety
 544       memset(reinterpret_cast<char*>(addr) + len, 0,
 545              sizeof(struct sockaddr_un) - len);
 546     }
 547     void copy(const ExternalUnixAddr &other) {
 548       CHECK(magic == kMagic);
 549       len = other.len;
 550       memcpy(addr, other.addr, len);
 551     }
 552     void free() {
 553       CHECK(magic == kMagic);
 554       delete addr;
 555       magic = 0;
 556     }
 557   };
 558
 559   // a typedef that allow us to compile against both winsock & POSIX sockets:
 560   // (both arg types and calling conventions differ for both)
 561   // POSIX: void setFromSocket(int socket,
 562   //                  int(*fn)(int, struct sockaddr*, socklen_t*));
 563   // mingw: void setFromSocket(unsigned socket,
 564   //                  int(*fn)(unsigned, struct sockaddr*, socklen_t*));
 565   using GetPeerNameFunc = decltype(getpeername);
 566
 567   struct addrinfo* getAddrInfo(const char* host, uint16_t port, int flags);
 568   struct addrinfo* getAddrInfo(const char* host, const char* port, int flags);
 569   void setFromAddrInfo(const struct addrinfo* results);
 570   void setFromLocalAddr(const struct addrinfo* results);
 571   void setFromSocket(SocketDesc socket, GetPeerNameFunc fn);
 572   std::string getIpString(int flags) const;
 573   void getIpString(char *buf, size_t buflen, int flags) const;
 574
 575   void updateUnixAddressLength(socklen_t addrlen);
 576
 577   void prepFamilyChange(sa_family_t newFamily) {
 578     if (newFamily != AF_UNIX) {
 579       if (external_) {
 580         storage_.un.free();
 581         storage_.addr = folly::IPAddress();
 582       }
 583       external_ = false;
 584     } else {
 585       if (!external_) {
 586         storage_.un.init();
 587       }
 588       external_ = true;
 589     }
 590   }
 591
 592   /*
 593    * storage_ contains room for a full IPv4 or IPv6 address, so they can be
 594    * stored inline without a separate allocation on the heap.
 595    *
 596    * If we need to store a Unix socket address, ExternalUnixAddr is a shim to
 597    * track a struct sockaddr_un allocated separately on the heap.
 598    */
 599   union {
 600     folly::IPAddress addr{};
 601     ExternalUnixAddr un;
 602   } storage_{};
 603   // IPAddress class does nto save zone or port, and must be saved here
 604   uint16_t port_;
 605
 606   bool external_{false};
 607 };
 608
 609 /**
 610  * Hash a SocketAddress object.
 611  *
 612  * boost::hash uses hash_value(), so this allows boost::hash to automatically
 613  * work for SocketAddress.
 614  */
 615 size_t hash_value(const SocketAddress& address);
 616
 617 std::ostream& operator<<(std::ostream& os, const SocketAddress& addr);
 618
 619 }
 620
 621 namespace std {
 622
 623 // Provide an implementation for std::hash<SocketAddress>
 624 template<>
 625 struct hash<folly::SocketAddress> {
 626   size_t operator()(
 627       const folly::SocketAddress& addr) const {
 628     return addr.hash();
 629   }
 630 };
 631
 632 }