WIP adding documentation

This commit is contained in:
Ritesh Chitlangi 2021-07-25 04:15:59 +08:00
parent c310e6f7b4
commit 28f744ea26
4 changed files with 108 additions and 2 deletions

View File

@ -1,3 +1,54 @@
//! Config load module
//!
//! Loads the configuration and credentials for each registry connection from
//! the `$XDG_CONFIG_HOME/epp-client/epp-client.toml` file
//!
//! ## Usage
//!
//! The config is automatically loaded when the module is initialized
//! and is available through the `epp_client::config::CONFIG` variable
//!
//! ## Sample config
//!
//! ```toml
//! [registry.verisign]
//! host = 'epp.verisign-grs.com'
//! port = 700
//! username = 'username'
//! password = 'password'
//! # service extensions
//! ext_uris = []
//!
//! [registry.hexonet.tls_files]
//! # the full client certificate chain in PEM format
//! cert_chain = '/path/to/certificate/chain/pemfile'
//! # the RSA private key for your certificate
//! key = '/path/to/private/key/pemfile'
//! ```
//!
//! ## Example
//!
//! ```rust
//! use epp_client::config::CONFIG;
//!
//! fn main() {
//! // Get configuration for the relevant registry section
//! let registry = CONFIG.registry("verisign").unwrap();
//!
//! // Get EPP host name and port no.
//! let remote = registry.connection_details();
//!
//! // Get username and password
//! let credentials = registry.credentials();
//!
//! // Get EPP service extensions
//! let service_extensions = registry.ext_uris().unwrap();
//!
//! // Get client certificate and private key
//! let tls = registry.tls_files().unwrap();
//! }
//! ```
use confy; use confy;
use lazy_static::lazy_static; use lazy_static::lazy_static;
use rustls::{Certificate, PrivateKey}; use rustls::{Certificate, PrivateKey};

View File

@ -1,2 +1,5 @@
//! Manages registry connections and reading/writing to them
//! and connects the EppClient instances to them
pub mod registry; pub mod registry;
pub mod client; pub mod client;

View File

@ -1,3 +1,31 @@
//! Manages sending/receiving EppObject request and responses to the registry connection
//!
//! ## Example
//!
//! ```rust
//! use epp_client::EppClient;
//! use epp_client::epp::{EppDomainCheck, EppDomainCheckResponse};
//!
//! #[tokio::main]
//! async fn main() {
//! // Create an instance of EppClient, specifying the name of the registry as in
//! // the config file
//! let mut client = match EppClient::new("verisign").await {
//! Ok(client) => client,
//! Err(e) => panic!("Failed to create EppClient: {}", e)
//! };
//!
//! // Make a EPP Hello call to the registry
//! let greeting = client.hello().await.unwrap();
//! println!("{:?}", greeting);
//!
//! // Execute an EPP Command against the registry with distinct request and response objects
//! let domain_check = EppDomainCheck::new(vec!["eppdev.com", "eppdev.net"], "client-trid-12345");
//! let response = client.transact::<_, EppDomainCheckResponse>(&domain_check).await.unwrap();
//! println!("{:?}", response);
//! }
//! ```
use futures::executor::block_on; use futures::executor::block_on;
use std::{error::Error, fmt::Debug}; use std::{error::Error, fmt::Debug};
// use std::time::SystemTime; // use std::time::SystemTime;
@ -49,6 +77,10 @@ async fn connect(registry: &'static str) -> Result<EppClient, Box<dyn Error>> {
Ok(client) Ok(client)
} }
/// Instances of the EppClient type are used to transact with the registry
/// An instance is first created, then various EPP request and response object
/// types are converted to EPP XML to be sent to the registry and the responses
/// from the registry are converted to local types
pub struct EppClient { pub struct EppClient {
credentials: (String, String), credentials: (String, String),
ext_uris: Option<Vec<String>>, ext_uris: Option<Vec<String>>,
@ -65,6 +97,7 @@ pub struct EppClient {
// } // }
impl EppClient { impl EppClient {
/// Fetches the username used in the registry connection
pub fn username(&self) -> String { pub fn username(&self) -> String {
self.credentials.0.to_string() self.credentials.0.to_string()
} }
@ -74,6 +107,8 @@ impl EppClient {
// self.client_tr_id_fn = Arc::new(func); // self.client_tr_id_fn = Arc::new(func);
// } // }
/// Creates a new EppClient object and does an EPP Login to a given registry to become ready
/// for subsequent transactions on this client instance
pub async fn new(registry: &'static str) -> Result<EppClient, Box<dyn Error>> { pub async fn new(registry: &'static str) -> Result<EppClient, Box<dyn Error>> {
connect(registry).await connect(registry).await
} }
@ -94,6 +129,7 @@ impl EppClient {
Ok(client) Ok(client)
} }
/// Executes an EPP Hello call and return the response as an `EppGreeting`
pub async fn hello(&mut self) -> Result<EppGreeting, Box<dyn Error>> { pub async fn hello(&mut self) -> Result<EppGreeting, Box<dyn Error>> {
let hello = EppHello::new(); let hello = EppHello::new();
let hello_xml = hello.serialize()?; let hello_xml = hello.serialize()?;
@ -103,6 +139,8 @@ impl EppClient {
Ok(EppGreeting::deserialize(&response)?) Ok(EppGreeting::deserialize(&response)?)
} }
/// Accepts an EPP request object to convert to a request to send to the registry. The response from the
/// registry is deserialized to response type E and returned.
pub async fn transact<T: EppXml + Debug, E: EppXml + Debug>(&mut self, request: &T) -> Result<E::Output, error::Error> { pub async fn transact<T: EppXml + Debug, E: EppXml + Debug>(&mut self, request: &T) -> Result<E::Output, error::Error> {
let epp_xml = request.serialize()?; let epp_xml = request.serialize()?;
@ -123,18 +161,23 @@ impl EppClient {
} }
} }
/// Accepts raw EPP XML and returns the raw EPP XML response to it.
/// Not recommended to use directly but sometimes can be useful for debugging
pub async fn transact_xml(&mut self, xml: &str) -> Result<String, Box<dyn Error>> { pub async fn transact_xml(&mut self, xml: &str) -> Result<String, Box<dyn Error>> {
self.connection.transact(&xml).await self.connection.transact(&xml).await
} }
/// Return the greeting received on establishment of the connection in raw xml form
pub fn xml_greeting(&self) -> String { pub fn xml_greeting(&self) -> String {
return String::from(&self.connection.greeting) return String::from(&self.connection.greeting)
} }
/// Return the greeting received on establishment of the connection as an `EppGreeting` instance
pub fn greeting(&self) -> Result<EppGreeting, error::Error> { pub fn greeting(&self) -> Result<EppGreeting, error::Error> {
EppGreeting::deserialize(&self.connection.greeting) EppGreeting::deserialize(&self.connection.greeting)
} }
/// Send the EPP Logout command to log out of the EPP session
pub async fn logout(&mut self) -> Result<EppCommandResponse, error::Error> { pub async fn logout(&mut self) -> Result<EppCommandResponse, error::Error> {
let client_tr_id = generate_client_tr_id(&self.credentials.0).unwrap(); let client_tr_id = generate_client_tr_id(&self.credentials.0).unwrap();
let epp_logout = EppLogout::new(client_tr_id.as_str()); let epp_logout = EppLogout::new(client_tr_id.as_str());

View File

@ -1,3 +1,5 @@
//! Manages registry connections and reading/writing to them
use std::sync::Arc; use std::sync::Arc;
use std::{str, u32}; use std::{str, u32};
use bytes::BytesMut; use bytes::BytesMut;
@ -10,11 +12,13 @@ use tokio::{net::TcpStream, io::AsyncWriteExt, io::AsyncReadExt, io::split, io::
use crate::config::{EppClientConnection}; use crate::config::{EppClientConnection};
use crate::error; use crate::error;
/// Socket stream for the connection to the registry
pub struct ConnectionStream { pub struct ConnectionStream {
reader: ReadHalf<TlsStream<TcpStream>>, reader: ReadHalf<TlsStream<TcpStream>>,
writer: WriteHalf<TlsStream<TcpStream>>, writer: WriteHalf<TlsStream<TcpStream>>,
} }
/// EPP Connection struct with some metadata for the connection
pub struct EppConnection { pub struct EppConnection {
registry: String, registry: String,
stream: ConnectionStream, stream: ConnectionStream,
@ -22,6 +26,7 @@ pub struct EppConnection {
} }
impl EppConnection { impl EppConnection {
/// Create an EppConnection instance with the stream to the registry
pub async fn new( pub async fn new(
registry: String, registry: String,
mut stream: ConnectionStream) -> Result<EppConnection, Box<dyn Error>> { mut stream: ConnectionStream) -> Result<EppConnection, Box<dyn Error>> {
@ -44,7 +49,7 @@ impl EppConnection {
Ok(()) Ok(())
} }
pub async fn send_epp_request(&mut self, content: &str) -> Result<(), Box<dyn Error>> { async fn send_epp_request(&mut self, content: &str) -> Result<(), Box<dyn Error>> {
let len = content.len(); let len = content.len();
let buf_size = len + 4; let buf_size = len + 4;
@ -93,7 +98,7 @@ impl EppConnection {
Ok(data) Ok(data)
} }
pub async fn get_epp_response(&mut self) -> Result<String, Box<dyn Error>> { async fn get_epp_response(&mut self) -> Result<String, Box<dyn Error>> {
let contents = self.read_epp_response().await?; let contents = self.read_epp_response().await?;
let response = str::from_utf8(&contents)?.to_string(); let response = str::from_utf8(&contents)?.to_string();
@ -101,6 +106,8 @@ impl EppConnection {
Ok(response) Ok(response)
} }
/// Send an EPP XML request to the registry and return the response
/// receieved to the request
pub async fn transact(&mut self, content: &str) -> Result<String, Box<dyn Error>> { pub async fn transact(&mut self, content: &str) -> Result<String, Box<dyn Error>> {
self.send_epp_request(&content).await?; self.send_epp_request(&content).await?;
@ -121,6 +128,8 @@ impl Drop for EppConnection {
} }
} }
/// Establish a TLS connection to a registry and return a ConnectionStream instance containing the
/// socket stream to read/write to the connection
pub async fn epp_connect(registry_creds: &EppClientConnection) -> Result<ConnectionStream, error::Error> { pub async fn epp_connect(registry_creds: &EppClientConnection) -> Result<ConnectionStream, error::Error> {
let (host, port) = registry_creds.connection_details(); let (host, port) = registry_creds.connection_details();