Module rspamd_ip

rspamd_ip is a helper module to simplify IP addresses manipulations.

Example:

local print_octets = function(ip)
        print('Normal order octets:')
        for _,o in ipairs(ip:str_octets()) do
                print(o)
        end
        print('Reversed order octets:')
        for _,o in ipairs(ip:inversed_str_octets()) do
                print(o)
        end
        print('Numeric octets:')
        for _,o in ipairs(ip:to_table()) do
                print(o)
        end
end

local rspamd_ip = require "rspamd_ip"
-- Create ipv4
local ip4 = rspamd_ip.from_string('127.0.0.1')
-- Implicit conversion to string
print(ip4)
-- Numeric version
print(ip4:get_version())
print_octets(ip4)

-- Create a sample ipv6 address
local ip6 = rspamd_ip.from_string('2001:41d0:8:dd9a::100')
print(ip6)
print(ip6:get_version())
print_octets(ip6)

Brief content:

Functions:

Function Description
rspamd_ip.from_string(line) Create IP address from its string representation.

Methods:

Method Description
ip:to_string([pretty=false]) Converts valid IP address to string.
ip:to_number() Converts valid IP address to number or list of numbers in case of IPv6.
ip:to_table() Converts valid IP address to the table of numeric octets.
ip:str_octets() Converts valid IP address to the table of string octets.
ip:inversed_str_octets() Converts valid IP address to the table of string octets in reversed order.
ip:__gc() Automatically destroys IP object.
ip:get_version() Gets numeric version of ip address.
ip:is_valid() Checks if an IP object is a valid IP address.
ip:apply_mask(mask) Applies mask to IP address, resetting up to mask least significant bits to zero.
ip:__eq(other) Compares two IP addresses.
ip:copy() Performs deep copy of IP address.
ip:is_local() Returns true if address is local one.
ip:less_than(other) Returns true if address is less than other.

Functions

The module rspamd_ip defines the following functions.

Function rspamd_ip.from_string(line)

Create IP address from its string representation.

Parameters:

  • line {string}: valid IP address string (either ipv4 or ipv6)

Returns:

  • {ip}: new ip object or nil if input is invalid

Back to module description.

Methods

The module rspamd_ip defines the following methods.

Method ip:to_string([pretty=false])

Converts valid IP address to string

Parameters:

  • pretty {bool}: print IP address with port and braces (for IPv6)

Returns:

  • {string or nil}: string representation of IP or nil if IP is invalid

Back to module description.

Method ip:to_number()

Converts valid IP address to number or list of numbers in case of IPv6

Parameters:

No parameters

Returns:

  • {integer(s) or nil}: numeric representation of IP in host byte order or nil if IP is invalid

Back to module description.

Method ip:to_table()

Converts valid IP address to the table of numeric octets

Parameters:

No parameters

Returns:

  • {table or nil}: numeric octets of IP address or nil if IP is invalid

Example:

local ip = rspamd_ip.from_string('127.0.0.1')
for _,o in ipairs(ip:to_table()) do
    print(o)
end
-- Output:
-- 127
-- 0
-- 0
-- 1

Back to module description.

Method ip:str_octets()

Converts valid IP address to the table of string octets. The difference from ip:to_table() is that this method returns just hex strings for ipv6 addresses.

Parameters:

No parameters

Returns:

  • {table or nil}: string octets of IP address or nil if IP is invalid

Example:

local ip = rspamd_ip.from_string('fe80::11')
print(table.concat(ip:str_octets(), "."))
-- Output:
-- f.e.8.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.1

Back to module description.

Method ip:inversed_str_octets()

Converts valid IP address to the table of string octets in reversed order. The difference from ip:to_table() is that this method returns just hex strings for ipv6 addresses in reversed order.

Parameters:

No parameters

Returns:

  • {table or nil}: string octets of IP address or nil if IP is invalid

Example:

local ip = rspamd_ip.from_string('fe80::11')
print(table.concat(ip:inversed_str_octets(), "."))
-- Output:
-- 1.1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.8.e.f

Back to module description.

Method ip:__gc()

Automatically destroys IP object.

Parameters:

No parameters

Returns:

No return

Back to module description.

Method ip:get_version()

Gets numeric version of ip address

Parameters:

No parameters

Returns:

  • {number}: 4 for IPv4 and 6 for IPv6

Back to module description.

Method ip:is_valid()

Checks if an IP object is a valid IP address.

Parameters:

No parameters

Returns:

  • {boolean}: true if IP is valid and false otherwise

Back to module description.

Method ip:apply_mask(mask)

Applies mask to IP address, resetting up to mask least significant bits to zero.

Parameters:

  • mask {integer}: how many bits to reset

Returns:

  • {ip}: new IP object with mask bits reset

Back to module description.

Method ip:__eq(other)

Compares two IP addresses

Parameters:

  • other {ip}: IP to compare

Returns:

  • {boolean}: true if two objects are the same

Back to module description.

Method ip:copy()

Performs deep copy of IP address.

Parameters:

No parameters

Returns:

  • {ip}: a fresh copy of IP address

Back to module description.

Method ip:is_local()

Returns true if address is local one

Parameters:

No parameters

Returns:

  • {boolean}: true if address is local

Back to module description.

Method ip:less_than(other)

Returns true if address is less than other

Parameters:

No parameters

Returns:

  • {boolean}: no description

Back to module description.

Back to top.