folly/SocketAddress.h

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