From 58c3cbfeb96b08fff78df3777453ecb48e57118f Mon Sep 17 00:00:00 2001 From: Dirkjan Ochtman Date: Thu, 2 Mar 2023 11:40:45 +0100 Subject: [PATCH] Update README and clean up documentation --- Cargo.toml | 2 +- README.md | 100 +++++++++++++++++++----------------------------- src/lib.rs | 110 ++++++++++++----------------------------------------- 3 files changed, 65 insertions(+), 147 deletions(-) diff --git a/Cargo.toml b/Cargo.toml index 92f4ab4..b8baa7c 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -4,7 +4,7 @@ version = "0.1.0" edition = "2021" rust-version = "1.59" license = "MIT" -description = "EPP (Extensible Provisioning Protocol) client library" +description = "EPP client library for async Rust" repository = "https://github.com/InstantDomain/instant-epp" [features] diff --git a/README.md b/README.md index 0f353ef..7f8bc9a 100644 --- a/README.md +++ b/README.md @@ -1,98 +1,78 @@ -# EPP (Extensible Provisioning Protocol) Library for Domain Registration and Management +# EPP client library for async Rust -[![Build](https://ci.masalachai.net/api/badges/masalachai/epp-client/status.svg)](https://ci.masalachai.net/masalachai/epp-client) -[![Documentation](https://docs.rs/epp-client/badge.svg)](https://docs.rs/epp-client/) +[![Documentation](https://docs.rs/instant-epp/badge.svg)](https://docs.rs/instant-epp) +[![Crates.io](https://img.shields.io/crates/v/instant-epp.svg)](https://crates.io/crates/instant-epp) +[![Build status](https://github.com/InstantDomain/instant-epp/workflows/CI/badge.svg)](https://github.com/InstantDomain/instant-epp/actions?query=workflow%3ACI) +[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE-MIT) ## Description -epp-client is a client library written in Rust for Internet domain registration -and management for domain registrars. +instant-epp is a client library written in Rust for Internet domain registration and management +for domain registrars. We have implemented support for the following standards: -It supports the following basic Domain, Contact, Host, and Message management -calls, with plans to add more calls and other EPP extensions in the future, and -to eventually be RFC compliant with the EPP protocol. +- [RFC 5730](https://tools.ietf.org/html/rfc5730) - Extensible Provisioning Protocol (EPP) +- [RFC 5731](https://tools.ietf.org/html/rfc5731) - Extensible Provisioning Protocol (EPP) Domain Name Mapping +- [RFC 5732](https://tools.ietf.org/html/rfc5732) - Extensible Provisioning Protocol (EPP) Host Mapping +- [RFC 5733](https://tools.ietf.org/html/rfc5733) - Extensible Provisioning Protocol (EPP) Contact Mapping +- [RFC 5734](https://tools.ietf.org/html/rfc5734) - Extensible Provisioning Protocol (EPP) Transport over TCP +- [RFC 3915](https://tools.ietf.org/html/rfc3915) - Domain Registry Grace Period Mapping +- [ConsoliDate mapping](https://www.verisign.com/assets/consolidate-mapping.txt) +- [Namestore Extension Mapping](https://www.verisign.com/assets/epp-sdk/verisign_epp-extension_namestoreext_v01.html) +- [Low Balance Mapping](https://www.verisign.com/assets/epp-sdk/verisign_epp-extension_low-balance_v01.html) -- Domain Check -- Domain Create -- Domain Info -- Domain Update -- Domain Delete -- Domain Renew -- Domain Transfer +This library is used in production with at [Instant Domains](https://instantdomains.com/). -- Contact Check -- Contact Create -- Contact Info -- Contact Update -- Contact Delete +## History -- Host Check -- Host Create -- Host Info -- Host Update -- Host Delete +instant-epp was originally created by [@masalachai](https://github.com/masalachai) as +[epp-client](https://github.com/masalachai/epp-client) in the summer of 2021. By fall, Instant +Domains employees started contributing to the project. In February of 2023, after most of the +contributions to epp-client had come from Instant Domains for the intervening years, we decided +to fork the project, replacing its dependency on quick-xml with +[instant-xml](https://github.com/InstantDomain/instant-xml/) in the process. Many thanks to +@masalachai for starting epp-client! -- Message Poll -- Message Ack - -- RGP Restore Request -- RGP Restore Report - -## Usage - -Just add the following to your project's `Cargo.toml` - -```toml -epp-client = "0.4" -``` - -## Operation +## Getting started You can create a mut variable of type `EppClient` with the domain registry config. ```rust +use std::collections::HashMap; use std::net::ToSocketAddrs; use std::time::Duration; -use epp_client::EppClient; -use epp_client::domain::DomainCheck; -use epp_client::login::Login; +use instant_epp::EppClient; +use instant_epp::domain::DomainCheck; +use instant_epp::common::NoExtension; #[tokio::main] async fn main() { // Create an instance of EppClient - let host = "example.com"; - let addr = (host, 700).to_socket_addrs().unwrap().next().unwrap(); let timeout = Duration::from_secs(5); - let mut client = match EppClient::connect("registry_name".to_string(), addr, host, None, timeout).await { + let mut client = match EppClient::connect("registry_name".to_string(), ("example.com".to_owned(), 7000), None, timeout).await { Ok(client) => client, Err(e) => panic!("Failed to create EppClient: {}", e) }; - let login = Login::new("username", "password", None); - client.transact(&login, "transaction-id").await.unwrap(); + // 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 = DomainCheck { domains: &["eppdev.com", "eppdev.net"] }; let response = client.transact(&domain_check, "transaction-id").await.unwrap(); - - response.res_data.unwrap().list + response + .res_data() + .unwrap() + .list .iter() - .for_each(|chk| println!("Domain: {}, Available: {}", chk.id, chk.available)); + .for_each(|chk| println!("Domain: {}, Available: {}", chk.inner.id, chk.inner.available)); } ``` The output would look like this: -```text +``` Domain: eppdev.com, Available: 1 Domain: eppdev.net, Available: 1 ``` - -## Request - -Currently I don't have access to a registry's OT&E account to do extensive -testing. I am using -[hexonet's EPP Gateway](https://wiki.hexonet.net/wiki/EPP_Gateway) for testing, -but access to a registry's OT&E account would be very helpful, so if anyone -could help me out with one I would be very grateful! diff --git a/src/lib.rs b/src/lib.rs index 7f5e986..e381a01 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,98 +1,36 @@ -//! # EPP (Extensible Provisioning Protocol) Client Library for Domain Registration and Management. +//! # EPP (Extensible Provisioning Protocol) client library for async Rust //! //! ## Description //! -//! epp-client is a client library for Internet domain registration and management for domain -//! registrars ([RFC 5730](https://tools.ietf.org/html/rfc5730)). It supports the following basic -//! management requests. +//! instant-epp is a client library written in Rust for Internet domain registration and management +//! for domain registrars. We have implemented support for the following standards: //! -//! Typically, you will start by initializing an [`EppClient`] instance, which will connect to the EPP server. -//! From there, you can submit requests using [`EppClient::transact()`]. +//! - [RFC 5730](https://tools.ietf.org/html/rfc5730) - Extensible Provisioning Protocol (EPP) +//! - [RFC 5731](https://tools.ietf.org/html/rfc5731) - Extensible Provisioning Protocol (EPP) Domain Name Mapping +//! - [RFC 5732](https://tools.ietf.org/html/rfc5732) - Extensible Provisioning Protocol (EPP) Host Mapping +//! - [RFC 5733](https://tools.ietf.org/html/rfc5733) - Extensible Provisioning Protocol (EPP) Contact Mapping +//! - [RFC 5734](https://tools.ietf.org/html/rfc5734) - Extensible Provisioning Protocol (EPP) Transport over TCP +//! - [RFC 3915](https://tools.ietf.org/html/rfc3915) - Domain Registry Grace Period Mapping +//! - [ConsoliDate mapping](https://www.verisign.com/assets/consolidate-mapping.txt) +//! - [Namestore Extension Mapping](https://www.verisign.com/assets/epp-sdk/verisign_epp-extension_namestoreext_v01.html) +//! - [Low Balance Mapping](https://www.verisign.com/assets/epp-sdk/verisign_epp-extension_low-balance_v01.html) //! -//! ## Core requests +//! This library is used in production with at [Instant Domains](https://instantdomains.com/). //! -//! - [`message::MessagePoll`] -//! - [`message::MessageAck`] +//! ## History //! -//! ## Domains +//! instant-epp was originally created by [@masalachai](https://github.com/masalachai) as +//! [epp-client](https://github.com/masalachai/epp-client) in the summer of 2021. By fall, Instant +//! Domains employees started contributing to the project. In February of 2023, after most of the +//! contributions to epp-client had come from Instant Domains for the intervening years, we decided +//! to fork the project, replacing its dependency on quick-xml with +//! [instant-xml](https://github.com/InstantDomain/instant-xml/) in the process. Many thanks to +//! @masalachai for starting epp-client! //! -//! Specified in [RFC 5731](https://tools.ietf.org/html/rfc5731). +//! ## Getting started //! -//! - [`domain::DomainCheck`] -//! - [`domain::DomainCreate`] -//! - [`domain::DomainInfo`] -//! - [`domain::DomainUpdate`] -//! - [`domain::DomainRenew`] -//! - [`domain::DomainTransfer`] -//! - [`domain::DomainDelete`] -//! -//! ## Contacts -//! -//! Specified in [RFC 5732](https://tools.ietf.org/html/rfc5732). -//! -//! - [`contact::ContactCheck`] -//! - [`contact::ContactCreate`] -//! - [`contact::ContactInfo`] -//! - [`contact::ContactUpdate`] -//! - [`contact::ContactDelete`] -//! -//! ## Hosts -//! -//! Specified in [RFC 5733](https://tools.ietf.org/html/rfc5733). -//! -//! - [`host::HostCheck`] -//! - [`host::HostCreate`] -//! - [`host::HostInfo`] -//! - [`host::HostUpdate`] -//! - [`host::HostDelete`] -//! -//! ## Extensions -//! -//! - [`extensions::rgp::report::RgpRestoreReport`] -//! - [`extensions::rgp::request::RgpRestoreRequest`] -//! - [`extensions::namestore::NameStore`] -//! - [`extensions::consolidate::Update`] -//! -//! ## Operation -//! -//! ```no_run -//! use std::net::ToSocketAddrs; -//! use std::time::Duration; -//! -//! use instant_epp::EppClient; -//! use instant_epp::domain::check::DomainCheck; -//! use instant_epp::login::Login; -//! -//! #[tokio::main] -//! async fn main() { -//! // Create an instance of EppClient -//! let timeout = Duration::from_secs(5); -//! let mut client = match EppClient::connect("registry_name".to_string(), ("example.com".to_owned(), 7000), None, timeout).await { -//! Ok(client) => client, -//! Err(e) => panic!("Failed to create EppClient: {}", e) -//! }; -//! -//! let login = Login::new("username", "password", None, None); -//! client.transact(&login, "transaction-id").await.unwrap(); -//! -//! // Execute an EPP Command against the registry with distinct request and response objects -//! let domain_check = DomainCheck { domains: &["eppdev.com", "eppdev.net"] }; -//! let response = client.transact(&domain_check, "transaction-id").await.unwrap(); -//! -//! response.res_data() -//! .unwrap() -//! .list -//! .iter() -//! .for_each(|chk| println!("Domain: {}, Available: {}", chk.inner.id, chk.inner.available)); -//! } -//! ``` -//! -//! The output would look similar to the following -//! -//! ```text -//! Domain: eppdev.com, Available: 1 -//! Domain: eppdev.net, Available: 1 -//! ``` +//! You will usually want to start by initializing an [`EppClient`]. Refer to the example code +//! on that type for more information. pub mod client; pub mod common;