Connections

Cripts will manage all client and server connections, in a set of objects that it manages for the user. This ownership again implies that access to these objects must be borrowed.

do_remap()
{
  static cripts::Matcher::Range::IP ALLOW_LIST({"192.168.201.0/24", "10.0.0.0/8"});
  borrow conn = cripts::Client::Connection::Get();
  auto client_ip = conn.IP();

  if (!ALLOW_LIST.contains(client_ip)) {
    // Deny the request (see examples for details)
  }
}

There are two kinds of connections provided by the run-time system:

Connection Object	Description
`cripts::Client::Connection`	The connection from the client to the ATS server.
`cripts::Server::Connection`	The connection from ATS to parent or origin server.

As usual, the cripts::Server::Connection object is only available assuming that the request is a forward proxy request, and you borrow it with the Get() method. On cache misses, there is no such connection.

Connection Methods

The connection objects provides a set of methods, used to access some internals details of the connections. These are:

Method	Description
`Count()`	The number of transactions processed on the connection so far.
`IP()`	The IP address of the connection.
`LocalIP()`	The server (ATS) IP address of the connection.
`IsInternal()`	Returns `true` or `false` if the connection is internal to ATS.
`Socket()`	Returns the raw socket structure for the connection (use with care).
`IsTLS()`	Returns `true` if the connection is a TLS connection.
`ClientCert()`	Returns the client certificiate (mTLS) for the connection (if any).
`ServerCert()`	Returns the server certificate for the connection, if it’s a TLS connection.

The IP() and LocalIP() methods return the IP address as an object. In addition to the automatic string conversion, it also has a special semantic string conversion which takes IPv4 and IPv6 CIDR sizes. For example:

do_remap()
{
  borrow conn = cripts::Client::Connection::Get();
  auto ip = conn.IP();

  CDebug("Client IP CIDR: {}", ip.string(24, 64));

IP Object Methods

The IP objects returned by IP() and LocalIP() methods provide additional functionality beyond string conversion:

Method	Description
`string()`	Convert IP to string with optional CIDR masking.
`Socket()`	Convert IP to a `sockaddr` structure for low-level socket operations.
`Hasher()`	Generate a hash value for the IP address.
`Sample()`	Determine if IP should be sampled based on rate and seed.
`ASN()`	Get ASN number (if Geo-IP support is available).
`ASNName()`	Get ASN name (if Geo-IP support is available).
`Country()`	Get country name (if Geo-IP support is available).
`CountryCode()`	Get country code (if Geo-IP support is available).

Note

The Geo-IP methods (ASN, ASNName, Country, CountryCode) are only available if ATS has been built with Geo-IP support. These methods can be used on any IP object, not just connection IPs.

Connection Variables

Both connection objects provide a number of variables that can be accessed. These are:

Variable	Description
`tcpinfo`	A number of TCPinfo related fields (see below).
`geo`	If available (compile time) access to Geo-IP data (see below).
`congestion`	Configure the congestion algorithm used on the socket.
`pacing`	Configure socket pacing for the connection.
`dscp`	Manage the DSCP value for the connection socket.
`mark`	Manage the Mark value for the connection socket.
`tls`	Access to the TLS object for the connection.

For other advanced features, a Cript has access to the socket file descriptor, via the FD() method of the connection object.

Note

For pacing, the special value cripts::Pacing::Off can be used to disable pacing.

Lets show an example of how one could use these variables:

do_remap()
{
  borrow conn = cripts::Client::Connection::Get();

  conn.congestion = "bbrv2";
  conn.pacing = 100;
  conn.dscp = 0x2e;
  conn.mark = 0x1;
}

TCPInfo Variables

The tcpinfo variable is a structure that provides access to the TCP information for the connection.

Field	Description
`rtt`	The round trip time for the connection.
`rto`	Retransmission timeout.
`retrans`	The number of retransmissions.
`snd_cwnd`	The congestion window.
`info`	The raw TCP information.

In addition to these convenience fields, the tcpinfo object provides a method to access the raw TCP information as well in the info field. There’s also a predefined log format, which can be accessed via the Log() method. See the tcpinfo plugin in ATS for details.

Geo-IP

If ATS has been built with Geo-IP support, both connection objects and IP objects will provide access to Geo-IP data. There are two ways to access Geo-IP information:

Connection-based Geo-IP

The connection object provides access to Geo-IP data for the connection’s IP address:

do_send_response()
{
  borrow conn = cripts::Client::Connection::Get();

  // This is supported, but probably prefer the IP-based approach below
  resp["X-ASN"] = conn.geo.ASN();
  resp["X-Country"] = conn.geo.Country();
}

IP-based Geo-IP

Any IP object can perform Geo-IP lookups directly:

do_send_response()
{
  borrow conn = cripts::Client::Connection::Get();
  auto client_ip = conn.IP();

  resp["X-ASN"] = client_ip.ASN();
  resp["X-Country"] = client_ip.Country();
}

The following methods are available for both approaches:

Method	Description
`ASN()`	The ASN number.
`ASNName()`	The name of the ASN.
`Country()`	Country.
`CountryCode()`	Country code.

Note

All methods return string values. These are methods and not fields, so they must be called as functions. The IP-based approach allows you to perform Geo-IP lookups on any IP address, not just connection IPs, making it more flexible for use cases where you have IP addresses from other sources.

TLS

The tls variable provides access to the TLS object for the session. This object provides access to the TLS certificate and other TLS related information. The following methods are available:

Method	Description
`Connection`	Returns the connection object for the TLS connection.
`GetX509()`	Returns the X509 certificate for the connection, an OpenSSL object.

Both of these can return a null pointer, if the connection is not a TLS connection or if the certificate is not available. The GetX509() method can take an optional boolean argument, which indicates if the certificate should be for a mutual TLS connection. The default is false, which means that the server certificate for the connection will be returned.