instant-labs
/
instant-epp
mirror of https://github.com/instant-labs/instant-epp.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update README and clean up documentation

This commit is contained in:
Dirkjan Ochtman 2023-03-02 11:40:45 +01:00
parent 3565e8eb07
commit 3905881b55
9 changed files with 87 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
Cargo.toml
View File

@ -4,7 +4,7 @@ version = "0.1.0"
edition = "2021" edition = "2021"
rust-version = "1.59" rust-version = "1.59"
license = "MIT" license = "MIT"
description = "EPP (Extensible Provisioning Protocol) client library" description = "EPP client library for async Rust"
repository = "https://github.com/InstantDomain/instant-epp" repository = "https://github.com/InstantDomain/instant-epp"
[features] [features]

100
README.md
View File

@ -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/instant-epp/badge.svg)](https://docs.rs/instant-epp)
[![Documentation](https://docs.rs/epp-client/badge.svg)](https://docs.rs/epp-client/) [![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 ## Description
epp-client is a client library written in Rust for Internet domain registration instant-epp is a client library written in Rust for Internet domain registration and management
and management for domain registrars. for domain registrars. We have implemented support for the following standards:
It supports the following basic Domain, Contact, Host, and Message management - [RFC 5730](https://tools.ietf.org/html/rfc5730) - Extensible Provisioning Protocol (EPP)
calls, with plans to add more calls and other EPP extensions in the future, and - [RFC 5731](https://tools.ietf.org/html/rfc5731) - Extensible Provisioning Protocol (EPP) Domain Name Mapping
to eventually be RFC compliant with the EPP protocol. - [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 This library is used in production at [Instant Domains](https://instantdomains.com/).
- Domain Create
- Domain Info
- Domain Update
- Domain Delete
- Domain Renew
- Domain Transfer
- Contact Check ## History
- Contact Create
- Contact Info
- Contact Update
- Contact Delete
- Host Check instant-epp was originally created by [@masalachai](https://github.com/masalachai) as
- Host Create [epp-client](https://github.com/masalachai/epp-client) in the summer of 2021. By fall, Instant
- Host Info Domains employees started contributing to the project. In February of 2023, after most of the
- Host Update contributions to epp-client had come from Instant Domains for the intervening years, we decided
- Host Delete 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 ## Getting started
- 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
You can create a mut variable of type `EppClient` with the domain registry config. You can create a mut variable of type `EppClient` with the domain registry config.
```rust ```rust
use std::collections::HashMap;
use std::net::ToSocketAddrs; use std::net::ToSocketAddrs;
use std::time::Duration; use std::time::Duration;
use epp_client::EppClient; use instant_epp::EppClient;
use epp_client::domain::DomainCheck; use instant_epp::domain::DomainCheck;
use epp_client::login::Login; use instant_epp::common::NoExtension;
#[tokio::main] #[tokio::main]
async fn main() { async fn main() {
// Create an instance of EppClient // 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 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, Ok(client) => client,
Err(e) => panic!("Failed to create EppClient: {}", e) Err(e) => panic!("Failed to create EppClient: {}", e)
}; };
let login = Login::new("username", "password", None); // Make a EPP Hello call to the registry
client.transact(&login, "transaction-id").await.unwrap(); let greeting = client.hello().await.unwrap();
println!("{:?}", greeting);
// Execute an EPP Command against the registry with distinct request and response objects // Execute an EPP Command against the registry with distinct request and response objects
let domain_check = DomainCheck { domains: &["eppdev.com", "eppdev.net"] }; let domain_check = DomainCheck { domains: &["eppdev.com", "eppdev.net"] };
let response = client.transact(&domain_check, "transaction-id").await.unwrap(); let response = client.transact(&domain_check, "transaction-id").await.unwrap();
response
response.res_data.unwrap().list .res_data()
.unwrap()
.list
.iter() .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: The output would look like this:
```text ```
Domain: eppdev.com, Available: 1 Domain: eppdev.com, Available: 1
Domain: eppdev.net, 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!

2
src/connection.rs
View File

@ -1,4 +1,6 @@
//! Manages registry connections and reading/writing to them //! Manages registry connections and reading/writing to them
//!
//! See also [RFC 5734](https://tools.ietf.org/html/rfc5734).
use std::future::Future; use std::future::Future;
use std::pin::Pin; use std::pin::Pin;

4
src/contact/mod.rs
View File

@ -1,3 +1,7 @@
//! Mapping for EPP contact objects
//!
//! As described in [RFC 5733](https://tools.ietf.org/html/rfc5733).
use std::borrow::Cow; use std::borrow::Cow;
use std::fmt; use std::fmt;
use std::str::FromStr; use std::str::FromStr;

4
src/domain/mod.rs
View File

@ -1,3 +1,7 @@
//! Mapping for EPP domain objects
//!
//! As described in [RFC 5731](https://tools.ietf.org/html/rfc5731).
use std::borrow::Cow; use std::borrow::Cow;
use std::fmt; use std::fmt;
use std::net::IpAddr; use std::net::IpAddr;

2
src/extensions/consolidate.rs
View File

@ -1,4 +1,6 @@
//! Types for EPP consolidate request //! Types for EPP consolidate request
//!
//! As described in [ConsoliDate mapping](https://www.verisign.com/assets/consolidate-mapping.txt)
use std::fmt; use std::fmt;

2
src/extensions/namestore.rs
View File

@ -1,4 +1,6 @@
//! Types for EPP namestore request and responses //! Types for EPP namestore request and responses
//!
//! As described in [Namestore Extension Mapping](https://www.verisign.com/assets/epp-sdk/verisign_epp-extension_namestoreext_v01.html).
use std::borrow::Cow; use std::borrow::Cow;

4
src/host/mod.rs
View File

@ -1,3 +1,7 @@
//! Mapping for EPP host objects
//!
//! As described in [RFC 5732](https://tools.ietf.org/html/rfc5732).
use std::borrow::Cow; use std::borrow::Cow;
use std::fmt; use std::fmt;
use std::net::IpAddr; use std::net::IpAddr;

114
src/lib.rs
View File

@ -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 //! ## Description
//! //!
//! epp-client is a client library for Internet domain registration and management for domain //! instant-epp is a client library written in Rust for Internet domain registration and management
//! registrars ([RFC 5730](https://tools.ietf.org/html/rfc5730)). It supports the following basic //! for domain registrars. We have implemented support for the following standards:
//! management requests.
//! //!
//! Typically, you will start by initializing an [`EppClient`] instance, which will connect to the EPP server. //! - [RFC 5730](https://tools.ietf.org/html/rfc5730) - Extensible Provisioning Protocol (EPP)
//! From there, you can submit requests using [`EppClient::transact()`]. //! - [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`] //! ## History
//! - [`message::MessageAck`]
//! //!
//! ## 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`] //! You will usually want to start by initializing an [`EppClient`]. Refer to the example code
//! - [`domain::DomainCreate`] //! on that type for more information.
//! - [`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
//! ```
pub mod client; pub mod client;
pub mod common; pub mod common;
@ -112,6 +50,10 @@ pub mod extensions {
pub mod consolidate; pub mod consolidate;
pub mod low_balance; pub mod low_balance;
pub mod namestore; pub mod namestore;
/// Mapping for the Registry Grace Period extension
///
/// As described in [RFC 3915](https://tools.ietf.org/html/rfc3915).
pub mod rgp { pub mod rgp {
pub mod report; pub mod report;
pub mod request; pub mod request;