whois_rust/
lib.rs

1/*!
2# WHOIS Rust
3
4This is a WHOIS client library for Rust, inspired by <https://github.com/hjr265/node-whois>
5
6## Usage
7
8You can make a **servers.json** file or copy one from <https://github.com/hjr265/node-whois>
9
10This is a simple example of **servers.json**.
11
12```json
13{
14    "org": "whois.pir.org",
15    "": "whois.ripe.net",
16    "_": {
17        "ip": {
18            "host": "whois.arin.net",
19            "query": "n + $addr\r\n"
20        }
21    }
22}
23```
24
25Then, use the `from_path` (or `from_string` if your JSON data is in-memory) associated function to create a `WhoIs` instance.
26
27```rust,ignore
28use whois_rust::WhoIs;
29
30let whois = WhoIs::from_path("/path/to/servers.json").unwrap();
31```
32
33Use the `lookup` method and input a `WhoIsLookupOptions` instance to lookup a domain or an IP.
34
35```rust,ignore
36use whois_rust::{WhoIs, WhoIsLookupOptions};
37
38let whois = WhoIs::from_path("/path/to/servers.json").unwrap();
39
40let result: String = whois.lookup(WhoIsLookupOptions::from_string("magiclen.org").unwrap()).unwrap();
41```
42
43The `lookup` method decodes the WHOIS response into a `String`. When the response is not valid UTF-8, it is decoded using the `charset` feature (enabled by default). If you need the exact bytes instead, use the `lookup_raw` method, which returns a `Vec<u8>`.
44
45A lookup follows the referral of a response up to `follow` times (2 by default). Each connection has its own `timeout` budget (60 seconds by default), so a lookup can take up to `follow + 1` times that value, and it accepts up to `max_response_size` bytes (4 MiB by default) instead of letting a broken or malicious server exhaust the memory. All of them can be changed through `WhoIsLookupOptions`.
46
47This crate implements the WHOIS protocol as specified in [RFC 3912](https://datatracker.ietf.org/doc/html/rfc3912): a request is a single line terminated with CRLF sent to TCP port 43, and the response is over when the server closes the connection. WHOIS has no authentication and no encryption, and no way to tell the character encoding of a response, which is why this crate has to guess it.
48
49## Asynchronous APIs
50
51You may want to use async APIs with your async runtime. This crate supports `tokio`, currently.
52
53```toml
54[dependencies.whois-rust]
55version = "*"
56features = ["tokio"]
57```
58
59After enabling the async feature, the `from_path_async` function and the `lookup_async` function are available.
60
61## Finding a WHOIS Server via DNS
62
63The `can_find_server_for_tld` method looks a WHOIS server up through the `_nicname._tcp` SRV records of a TLD. It needs a DNS client, so it is put behind the `srv` feature, which is disabled by default.
64
65```toml
66[dependencies.whois-rust]
67version = "*"
68features = ["srv"]
69```
70
71## Testing
72
73```bash
74# git clone --recurse-submodules https://github.com/magiclen/whois-rust.git
75
76git clone https://github.com/magiclen/whois-rust.git
77
78cd whois-rust
79
80git submodule init
81git submodule update --recursive
82
83cargo test
84```
85*/
86
87#![cfg_attr(docsrs, feature(doc_cfg))]
88
89#[cfg(feature = "tokio")]
90pub use tokio;
91pub use validators;
92
93mod target;
94mod who_is;
95mod who_is_error;
96mod who_is_host;
97mod who_is_lookup_options;
98mod who_is_server_value;
99
100pub use target::*;
101pub use who_is::*;
102pub use who_is_error::*;
103pub use who_is_host::*;
104pub use who_is_lookup_options::*;
105pub use who_is_server_value::*;
whois_rust/lib.rs

whois_rust/
lib.rs
