folly/SocketAddress.h

   1 /*
   2  * Copyright 2015 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
  31 namespace folly {
  32
  33 class SocketAddress {
  34  public:
  35   SocketAddress() = default;
  36
  37   /**
  38    * Construct a SocketAddress from a hostname and port.
  39    *
  40    * Note: If the host parameter is not a numeric IP address, hostname
  41    * resolution will be performed, which can be quite slow.
  42    *
  43    * Raises std::system_error on error.
  44    *
  45    * @param host The IP address (or hostname, if allowNameLookup is true)
  46    * @param port The port (in host byte order)
  47    * @pram allowNameLookup  If true, attempt to perform hostname lookup
  48    *        if the hostname does not appear to be a numeric IP address.
  49    *        This is potentially a very slow operation, so is disabled by
  50    *        default.
  51    */
  52   SocketAddress(const char* host, uint16_t port,
  53                  bool allowNameLookup = false) {
  54     // Initialize the address family first,
  55     // since setFromHostPort() and setFromIpPort() will check it.
  56
  57     if (allowNameLookup) {
  58       setFromHostPort(host, port);
  59     } else {
  60       setFromIpPort(host, port);
  61     }
  62   }
  63
  64   SocketAddress(const std::string& host, uint16_t port,
  65                  bool allowNameLookup = false) {
  66     // Initialize the address family first,
  67     // since setFromHostPort() and setFromIpPort() will check it.
  68
  69     if (allowNameLookup) {
  70       setFromHostPort(host.c_str(), port);
  71     } else {
  72       setFromIpPort(host.c_str(), port);
  73     }
  74   }
  75
  76   SocketAddress(const IPAddress& ipAddr, uint16_t port) {
  77     setFromIpAddrPort(ipAddr, port);
  78   }
  79
  80   SocketAddress(const SocketAddress& addr) {
  81     port_ = addr.port_;
  82     if (addr.getFamily() == AF_UNIX) {
  83       storage_.un.init(addr.storage_.un);
  84     } else {
  85       storage_ = addr.storage_;
  86     }
  87     external_ = addr.external_;
  88   }
  89
  90   SocketAddress& operator=(const SocketAddress& addr) {
  91     if (!external_) {
  92       if (addr.getFamily() != AF_UNIX) {
  93         storage_ = addr.storage_;
  94       } else {
  95         storage_ = addr.storage_;
  96         storage_.un.init(addr.storage_.un);
  97       }
  98     } else {
  99       if (addr.getFamily() == AF_UNIX) {
 100         storage_.un.copy(addr.storage_.un);
 101       } else {
 102         storage_.un.free();
 103         storage_ = addr.storage_;
 104       }
 105     }
 106     port_ = addr.port_;
 107     external_ = addr.external_;
 108     return *this;
 109   }
 110
 111   SocketAddress(SocketAddress&& addr) noexcept {
 112     storage_ = addr.storage_;
 113     port_ = addr.port_;
 114     external_ = addr.external_;
 115     addr.external_ = false;
 116   }
 117
 118   SocketAddress& operator=(SocketAddress&& addr) {
 119     std::swap(storage_, addr.storage_);
 120     std::swap(port_, addr.port_);
 121     std::swap(external_, addr.external_);
 122     return *this;
 123   }
 124
 125   ~SocketAddress() {
 126     if (external_) {
 127       storage_.un.free();
 128     }
 129   }
 130
 131   bool isInitialized() const {
 132     return (getFamily() != AF_UNSPEC);
 133   }
 134
 135   /**
 136    * Return whether this address is within private network.
 137    *
 138    * According to RFC1918, the 10/8 prefix, 172.16/12 prefix, and 192.168/16
 139    * prefix are reserved for private networks.
 140    * fc00::/7 is the IPv6 version, defined in RFC4139.  IPv6 link-local
 141    * addresses (fe80::/10) are also considered private addresses.
 142    *
 143    * The loopback addresses 127/8 and ::1 are also regarded as private networks
 144    * for the purpose of this function.
 145    *
 146    * Returns true if this is a private network address, and false otherwise.
 147    */
 148   bool isPrivateAddress() const;
 149
 150   /**
 151    * Return whether this address is a loopback address.
 152    */
 153   bool isLoopbackAddress() const;
 154
 155   void reset() {
 156     prepFamilyChange(AF_UNSPEC);
 157   }
 158
 159   /**
 160    * Initialize this SocketAddress from a hostname and port.
 161    *
 162    * Note: If the host parameter is not a numeric IP address, hostname
 163    * resolution will be performed, which can be quite slow.
 164    *
 165    * If the hostname resolves to multiple addresses, only the first will be
 166    * returned.
 167    *
 168    * Raises std::system_error on error.
 169    *
 170    * @param host The hostname or IP address
 171    * @param port The port (in host byte order)
 172    */
 173   void setFromHostPort(const char* host, uint16_t port);
 174
 175   void setFromHostPort(const std::string& host, uint16_t port) {
 176     setFromHostPort(host.c_str(), port);
 177   }
 178
 179   /**
 180    * Initialize this SocketAddress from an IP address and port.
 181    *
 182    * This is similar to setFromHostPort(), but only accepts numeric IP
 183    * addresses.  If the IP string does not look like an IP address, it throws a
 184    * std::invalid_argument rather than trying to perform a hostname resolution.
 185    *
 186    * Raises std::system_error on error.
 187    *
 188    * @param ip The IP address, as a human-readable string.
 189    * @param port The port (in host byte order)
 190    */
 191   void setFromIpPort(const char* ip, uint16_t port);
 192
 193   void setFromIpPort(const std::string& ip, uint16_t port) {
 194     setFromIpPort(ip.c_str(), port);
 195   }
 196
 197   /**
 198    * Initialize this SocketAddress from an IPAddress struct and port.
 199    *
 200    * @param ip The IP address in IPAddress format
 201    * @param port The port (in host byte order)
 202    */
 203   void setFromIpAddrPort(const IPAddress& ip, uint16_t port);
 204
 205   /**
 206    * Initialize this SocketAddress from a local port number.
 207    *
 208    * This is intended to be used by server code to determine the address to
 209    * listen on.
 210    *
 211    * If the current machine has any IPv6 addresses configured, an IPv6 address
 212    * will be returned (since connections from IPv4 clients can be mapped to the
 213    * IPv6 address).  If the machine does not have any IPv6 addresses, an IPv4
 214    * address will be returned.
 215    */
 216   void setFromLocalPort(uint16_t port);
 217
 218   /**
 219    * Initialize this SocketAddress from a local port number.
 220    *
 221    * This version of setFromLocalPort() accepts the port as a string.  A
 222    * std::invalid_argument will be raised if the string does not refer to a port
 223    * number.  Non-numeric service port names are not accepted.
 224    */
 225   void setFromLocalPort(const char* port);
 226   void setFromLocalPort(const std::string& port) {
 227     return setFromLocalPort(port.c_str());
 228   }
 229
 230   /**
 231    * Initialize this SocketAddress from a local port number and optional IP
 232    * address.
 233    *
 234    * The addressAndPort string may be specified either as "<ip>:<port>", or
 235    * just as "<port>".  If the IP is not specified, the address will be
 236    * initialized to 0, so that a server socket bound to this address will
 237    * accept connections on all local IP addresses.
 238    *
 239    * Both the IP address and port number must be numeric.  DNS host names and
 240    * non-numeric service port names are not accepted.
 241    */
 242   void setFromLocalIpPort(const char* addressAndPort);
 243   void setFromLocalIpPort(const std::string& addressAndPort) {
 244     return setFromLocalIpPort(addressAndPort.c_str());
 245   }
 246
 247   /**
 248    * Initialize this SocketAddress from an IP address and port number.
 249    *
 250    * The addressAndPort string must be of the form "<ip>:<port>".  E.g.,
 251    * "10.0.0.1:1234".
 252    *
 253    * Both the IP address and port number must be numeric.  DNS host names and
 254    * non-numeric service port names are not accepted.
 255    */
 256   void setFromIpPort(const char* addressAndPort);
 257   void setFromIpPort(const std::string& addressAndPort) {
 258     return setFromIpPort(addressAndPort.c_str());
 259   }
 260
 261   /**
 262    * Initialize this SocketAddress from a host name and port number.
 263    *
 264    * The addressAndPort string must be of the form "<host>:<port>".  E.g.,
 265    * "www.facebook.com:443".
 266    *
 267    * If the host name is not a numeric IP address, a DNS lookup will be
 268    * performed.  Beware that the DNS lookup may be very slow.  The port number
 269    * must be numeric; non-numeric service port names are not accepted.
 270    */
 271   void setFromHostPort(const char* hostAndPort);
 272   void setFromHostPort(const std::string& hostAndPort) {
 273     return setFromHostPort(hostAndPort.c_str());
 274   }
 275
 276   /**
 277    * Initialize this SocketAddress from a local unix path.
 278    *
 279    * Raises std::invalid_argument on error.
 280    */
 281   void setFromPath(const char* path) {
 282     setFromPath(path, strlen(path));
 283   }
 284
 285   void setFromPath(const std::string& path) {
 286     setFromPath(path.data(), path.length());
 287   }
 288
 289   void setFromPath(const char* path, size_t length);
 290
 291   /**
 292    * Initialize this SocketAddress from a socket's peer address.
 293    *
 294    * Raises std::system_error on error.
 295    */
 296   void setFromPeerAddress(int 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(int socket);
 304
 305   /**
 306    * Initialize this TSocketAddress 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   struct addrinfo* getAddrInfo(const char* host, uint16_t port, int flags);
 560   struct addrinfo* getAddrInfo(const char* host, const char* port, int flags);
 561   void setFromAddrInfo(const struct addrinfo* results);
 562   void setFromLocalAddr(const struct addrinfo* results);
 563   void setFromSocket(int socket, int (*fn)(int, struct sockaddr*, socklen_t*));
 564   std::string getIpString(int flags) const;
 565   void getIpString(char *buf, size_t buflen, int flags) const;
 566
 567   void updateUnixAddressLength(socklen_t addrlen);
 568
 569   void prepFamilyChange(sa_family_t newFamily) {
 570     if (newFamily != AF_UNIX) {
 571       if (external_) {
 572         storage_.un.free();
 573         storage_.addr = folly::IPAddress();
 574       }
 575       external_ = false;
 576     } else {
 577       if (!external_) {
 578         storage_.un.init();
 579       }
 580       external_ = true;
 581     }
 582   }
 583
 584   /*
 585    * storage_ contains room for a full IPv4 or IPv6 address, so they can be
 586    * stored inline without a separate allocation on the heap.
 587    *
 588    * If we need to store a Unix socket address, ExternalUnixAddr is a shim to
 589    * track a struct sockaddr_un allocated separately on the heap.
 590    */
 591   union {
 592     folly::IPAddress addr{};
 593     ExternalUnixAddr un;
 594   } storage_{};
 595   // IPAddress class does nto save zone or port, and must be saved here
 596   uint16_t port_;
 597
 598   bool external_{false};
 599 };
 600
 601 /**
 602  * Hash a SocketAddress object.
 603  *
 604  * boost::hash uses hash_value(), so this allows boost::hash to automatically
 605  * work for SocketAddress.
 606  */
 607 size_t hash_value(const SocketAddress& address);
 608
 609 std::ostream& operator<<(std::ostream& os, const SocketAddress& addr);
 610
 611 }
 612
 613 namespace std {
 614
 615 // Provide an implementation for std::hash<SocketAddress>
 616 template<>
 617 struct hash<folly::SocketAddress> {
 618   size_t operator()(
 619       const folly::SocketAddress& addr) const {
 620     return addr.hash();
 621   }
 622 };
 623
 624 }