# Functions

## `blst_add([timeout])`

Adds the source of the current message to the blocklist for `timeout` seconds. If timeout is missing or 0 it uses the default blocklist timeout (`dst_blocklist_expire`).

### `blst_add` usage

    ...
    if (src_ip==10.0.0.0/9)
        blst_add(30); # 30 s
    else
        blst_add();  # use default blocklist timeout
    ...

## `blst_add_retry_after(min, max)`

Adds the source of the current message to the blocklist for the time interval specified in the Retry-After header. If the Retry-After header is missing, it will fail (returns false). If the Retry-After value is less than `min`, then `min` seconds will be used instead. If the Retry-After value is greater than `max`, then `max` seconds will be used instead.

### `blst_add_retry_after` usage

    ...
    # on_reply route
    if (msg_status==503){ # blocklist 503 source for Retry-After seconds
        if (! blst_add_retry_after(30, 3600))
            blst_add(60); # if no retry_after header add it for 60s
    }
    ...

## `blst_del()`

Removes the source of the current message from the blocklist. If the address is not present in the blocklist at the time of the call it returns false.

### `blst_del` usage

    ...
        blst_del();
    ...

## `blst_is_blocklisted()`

Returns true if the source of the current message is blocklisted.

### `blst_is_blocklisted` usage

    ...
        if (blst_is_blocklisted()){
            log("message from a blocklisted source");
            drop;
       }
    ...

## `blst_set_ignore([flags])`

Set errors that will not be taken into account when deciding whether to blocklist a destination for the current message or a local reply to the current message.

`blst_set_ignore(..)` works for forwarding the current message and `blst_rpl_set_ignore(...)` works for local replies to the current message.

The variants of these functions with no parameters will ignore everything (equivalent to passing 0xff).

The flags are stored internally as a bitmask, and are applied by bitwise ANDing them together. The following flags are available:

- 0x02 - generic send error (send denied/ failed).
- 0x04 - connect failed (TCP, TLS or SCTP).
- 0x08 - ICMP error (not currently used).
- 0x10 - SIP transaction timeout.
- 0x20 - 503 reply (stateful mode only). For more details see tm `blst_503`.

TCP and TLS send and connect errors are handled per connection and not per message. The connection blocklist ignore flags are inherited from the message that caused the connection establishment.

### `blst_set_ignore` usage

    ...
        blst_set_ignore(6); # ignore send and connect errors
    ...

## `blst_rpl_set_ignore([flags])`

See function `blst_set_ignore([flags])`.

## `blst_clear_ignore([flags])`

Clears blocklist ignore flags previously set by the corresponding `blst_set_ignore(...)` or `blst_rpl_set_ignore(...)` functions.

See also `blst_set_ignore`.

### `blst_clear_ignore` usage

    ...
        blst_clear_ignore(4); # ignore connect errors
    ...

## `blst_rpl_clear_ignore([flags])`

See function `blst_clear_ignore([flags])`.