Line data    Source code

       1             : #ifndef HEADER_fd_src_waltz_http_fd_url_h
       2             : #define HEADER_fd_src_waltz_http_fd_url_h
       3             : 
       4             : /* fd_url.h provides an API for handling URLs.
       5             : 
       6             :    This API is by no means compliant.  Works only for basic strings.  */
       7             : 
       8             : #include "../../util/fd_util_base.h"
       9             : #include "../fd_fqdn.h"
      10             : 
      11             : /* fd_url_t holds a bunch of pointers into an URL string. */
      12             : 
      13             : struct fd_url {
      14             :   char const * scheme;
      15             :   ulong        scheme_len;
      16             : 
      17             :   char const * host;
      18             :   ulong        host_len; /* <FD_FQDN_BUF_MAX */
      19             : 
      20             :   char const * port;
      21             :   ulong        port_len;
      22             : 
      23             :   char const * tail; /* path, query, fragment */
      24             :   ulong        tail_len;
      25             : };
      26             : 
      27             : typedef struct fd_url fd_url_t;
      28             : 
      29          51 : #define FD_URL_SUCCESS         0
      30           3 : #define FD_URL_ERR_SCHEME      1
      31           3 : #define FD_URL_ERR_HOST_OVERSZ 2
      32           3 : #define FD_URL_ERR_USERINFO    3
      33             : 
      34             : /* Storage required for an HTTP(S) origin containing a maximum-sized
      35             :    host and an explicit five-digit port, including the terminating NUL.
      36             :    Paths, queries, and fragments are not included. */
      37          12 : #define FD_URL_FORMAT_OVERHEAD (14UL)
      38          12 : #define FD_URL_MAX             (FD_FQDN_BUF_MAX+FD_URL_FORMAT_OVERHEAD)
      39             : 
      40             : FD_PROTOTYPES_BEGIN
      41             : 
      42             : /* fd_url_parse_cstr is a basic URL parser.  It is not RFC compliant.
      43             : 
      44             :    Non-exhaustive list of what this function cannot do:
      45             :    - Schemes other than http and https are not supported
      46             :    - userinfo (e.g. 'user:pass@') is not supported
      47             :    - Anything after the authority is ignored
      48             : 
      49             :    If opt_err!=NULL, on return *opt_err holds an FD_URL_ERR_{...} code. */
      50             : 
      51             : fd_url_t *
      52             : fd_url_parse_cstr( fd_url_t *   url,
      53             :                    char const * url_str,
      54             :                    ulong        url_str_len,
      55             :                    int *        opt_err );
      56             : 
      57             : /* Shared validator/runtime URL gate.
      58             :    Accepts a http(s):// URL, fills fd_url_t `url` parameter.
      59             :      - Only `http://` and `https://` schemes are permitted.  Anything
      60             :        else (including missing schemes or stray slashes) is rejected.
      61             :        The `context` string is echoed in the log so operators know which
      62             :        knob supplied the bad value.
      63             :      - If the URL omits an explicit port we default to 443/80 and then flip
      64             :        `is_ssl` based on the scheme so downstream sockets know whether
      65             :        to open TLS.
      66             :      - Hosts containing FD_FQDN_BUF_MAX bytes or more are rejected
      67             :    The function does not enforce the host being non-empty; that is left to
      68             :    the caller because some control paths treat an empty host differently
      69             :    (e.g. surfacing a custom error message).
      70             :    Returns 0 on success, -1 on failure (and logs a warning). */
      71             : 
      72             : int
      73             : fd_url_parse_endpoint( fd_url_t *   url,
      74             :                        char const * url_str,
      75             :                        ulong        url_str_len,
      76             :                        ushort *     tcp_port,
      77             :                        _Bool *      is_ssl,
      78             :                        char const * context );
      79             : 
      80             : /* fd_url_unescape undoes % escapes in-place.  Returns the unescaped
      81             :    length on success, or 0 on failure (invalid hex digit or truncated
      82             :    percent encoding). */
      83             : 
      84             : ulong
      85             : fd_url_unescape( char * msg,
      86             :                  ulong  len );
      87             : 
      88             : FD_PROTOTYPES_END
      89             : 
      90             : #endif /* HEADER_fd_src_waltz_http_fd_url_h */