2 URLs and HTTP

To access the text of a document from the web, first obtain its URL as a string. Convert the address into a url structure using string->url. Then, open the document using get-pure-port or get-impure-port, depending on whether or not you wish to examine its MIME headers. At this point, you have a regular input port with which to process the document, as with any other file.

Currently the only supported protocols are "http", "https", and sometimes "file".

The net/url logs information and background-thread errors to a logger named 'net/url.

2.1 URL Structure

The strings inside the user, path, query, and fragment fields are represented directly as Racket strings, without URL-syntax-specific quoting. The procedures string->url and url->string translate encodings such as %20 into spaces and back again.

By default, query associations are parsed with either ; or & as a separator, and they are generated with & as a separator. The current-alist-separator-mode parameter adjusts the behavior.

An empty string at the end of the path list corresponds to a URL that ends in a slash. For example, the result of (string->url "http://racket-lang.org/a/") has a path field with strings "a" and "", while the result of (string->url "http://racket-lang.org/a") has a path field with only the string "a".

When a "file" URL is represented by a url structure, the path field is mostly a list of path elements. For Unix paths, the root directory is not included in path; its presence or absence is implicit in the path-absolute? flag. For Windows paths, the first element typically represents a drive, but a UNC path is represented by a first element that is "" and then successive elements complete the drive components that are separated by / or \.

2.2 URL Parsing Functions

The contract on str insists that, if the url has a scheme, then the scheme begins with a letter and consists only of letters, numbers, +, -, and . characters.

If str starts with file: (case-insensitively) and the value of the file-url-path-convention-type parameter is 'windows, then special parsing rules apply to accommodate ill-formed but widely-recognized path encodings:

• If file: is followed by //, a letter, and :, then the // is stripped and the remainder parsed as a Windows path.

• If file: is followed by \\, then the \\ is stripped and the remainder parsed as a Windows path.

In both of these cases, the host is "", the port is #f, and path-element decoding (which extract parameters or replaces %20 with a space, for example) is not applied to the path.

This function does not raise any exceptions.

The url->string procedure uses alist->form-urlencoded when formatting the query, so it is sensitive to the current-alist-separator-mode parameter for determining the association separator. The default is to separate associations with a &.

The encoding of path segments and fragment is sensitive to the current-url-encode-mode parameter.

With the 'unix path convention, the host in the resulting URL is always "", and the path is absolute from the root.

With the 'windows path convention and a UNC path, the machine part of the UNC root is used as the URL’s host, and the drive part of the root is the first element of the URL’s path.

Changed in version 6.3.0.1 of package base: Changed 'windows encoding of UNC paths.

For the 'unix path convention, the URL’s host is ignored, and the URL’s path is formed relative to the root.

For the 'windows path convention:

• A non-"" value for the URL’s host field creates a UNC path, where the host is the UNC root’s machine name, the URL’s path must be non-empty, and the first element of the URL’s path is used as the drive part of the UNC root.

• For legacy reasons, if the URL’s host is "", the URL’s path contains at least three elements, and and the first element of the URL’s path is also "", then a UNC path is created by using the second and third elements of the path as the UNC root’s machine and drive, respectively.

• Otherwise, the URL’s path is converted to a Windows path. The result is an absolute path if the URL’s first path element corresponds to a drive, otherwise the result is a relative path (even though URLs are not intended to represent relative paths).

Changed in version 6.3.0.1 of package base: Changed 'windows treatment of a non-"" host.

Internally, 'recommended mode uses uri-path-segment-encode and uri-encode, while 'unreserved mode uses uri-path-segment-unreserved-encode and uri-unreserved-encode.

2.3 URL Functions

An HTTP connection is created as a pure port or a impure port. A pure port is one from which the MIME headers have been removed, so that what remains is purely the first content fragment. An impure port is one that still has its MIME headers.

The GET method is used to retrieve whatever information is identified by URL. If redirections is not 0, then get-pure-port will follow redirections from the server, up to the limit given by redirections.

The HEAD method is identical to GET, except the server must not return a message body. The meta-information returned in a response to a HEAD request should be identical to the information in a response to a GET request.

The DELETE method is used to delete the entity identified by URL.

Beware: By default, "https" scheme handling does not verify a server’s certificate (i.e., it’s equivalent of clicking through a browser’s warnings), so communication is safe, but the identity of the server is not verified. To validate the server’s certificate, set current-https-protocol to 'secure or a context created with ssl-secure-client-context.

The "file" scheme for URLs is handled only by get-pure-port, which uses open-input-file, does not handle exceptions, and ignores the optional strings.

Changed in version 6.1.1.8 of package base: Added options-pure-port.

Changed in version 6.1.1.8 of package base: Added options-impure-port.

Beware: See get-pure-port for warnings about "https" certificate validation.

The net/head library provides procedures, such as extract-field for manipulating the header.

Since web servers sometimes return mis-formatted replies, purify-port is liberal in what it accepts as a header. as a result, the result string may be ill formed, but it will either be the empty string, or it will be a string matching the following regexp:

#rx"^HTTP/.*?(\r\n\r\n|\n\n|\r\r)"

The get-pure-port/headers function performs a GET request on url, follows up to redirections redirections and returns a port containing the data as well as the headers for the final connection. If status? is true, then the status line is included in the result string.

A given connection should be used for communication with a particular HTTP/1.1 server, unless connection is closed (via http-connection-close) between uses for different servers. If connection is provided, read all data from the result port before making a new request with the same connection. (Reusing a connection without reading all data may or may not work.)

The make-http-connection creates a “connection” that is initially unconnected. Each call to get-pure-port/headers leaves a connection either connected or unconnected, depending on whether the server allows the connection to continue. The http-connection-close function unconnects, but it does not prevent further use of the connection value.

When a header argument is supplied, it is passed along to the connect procedure.

The connection is made in such a way that the port is closed before call/input-url returns, no matter how it returns. In particular, it is closed if handle raises an exception, or if the connection process is interruped by an asynchronous break exception.

• the URL scheme, such as "http", where proxiable-url-schemes lists the URL schemes that can be proxied; currently, the only proxiable scheme is "http";

• the proxy server address; and

• the proxy server port number.

The initial value of current-proxy-servers is configured on demand from the environment variables plt_http_proxy and http_proxy, where the former takes precedence over the latter. Each environment variable contains a single URL of the form http://‹hostname›:‹portno›. If any other components of the URL are provided, an error will be logged to a net/url logger.

The default mapping is the empty list (i.e., no proxies).

• strings that match host names exactly; and

• regexps that match host by pattern.

If a proxy server is defined for a URL scheme, then the destination host name is checked against current-no-proxy-servers. The proxy is used if and only if the host name does not match (by the definition above) any in the list.

• a string beginning with a . (period): converted to a regexp that performs a suffix match on a destination host name; e.g. .racket-lang.org matches destinations of doc.racket-lang.org, pkgs.racket-lang.org, but neither doc.bracket-lang.org nor pkgs.racket-lang.org.uk;

• any other string: converted to a regexp that matches the string exactly.

This function does not support proxies.

2.4 URL HTTPS mode

These bindings are provided by the net/url-connect library, and used by net/url.

2.5 URL Unit

url@, url^, and url+scheme^ are deprecated. They exist for backward-compatibility and will likely be removed in the future. New code should use the net/url module.

The url+scheme^ signature contains current-connect-scheme, which url@ binds to a parameter. The parameter is set to the scheme of a URL when tcp-connect is called to create a connection. A tcp-connect variant linked to url@ can check this parameter to choose the connection mode; in particular, net/url supplies a tcp-connect that actually uses ssl-connect when (current-connect-scheme) produces "https".

Note that net/url does not provide the current-connect-scheme parameter.

2.6 URL Signature