Trait trust_dns::client::ClientHandle [−] [src]

#[must_use = "queries can only be sent through a ClientHandle"]

pub trait ClientHandle: Clone {
    fn send(
        &mut self, 
        message: Message
    ) -> Box<Future<Item = Message, Error = ClientError>>;

    fn query(
        &mut self, 
        name: Name, 
        query_class: DNSClass, 
        query_type: RecordType
    ) -> Box<Future<Item = Message, Error = ClientError>> { ... }

    fn notify<R>(
        &mut self, 
        name: Name, 
        query_class: DNSClass, 
        query_type: RecordType, 
        rrset: Option<R>
    ) -> Box<Future<Item = Message, Error = ClientError>>
    where
        R: IntoRecordSet,
    { ... }

    fn create<R>(
        &mut self, 
        rrset: R, 
        zone_origin: Name
    ) -> Box<Future<Item = Message, Error = ClientError>>
    where
        R: IntoRecordSet,
    { ... }

    fn append<R>(
        &mut self, 
        rrset: R, 
        zone_origin: Name, 
        must_exist: bool
    ) -> Box<Future<Item = Message, Error = ClientError>>
    where
        R: IntoRecordSet,
    { ... }

    fn compare_and_swap<C, N>(
        &mut self, 
        current: C, 
        new: N, 
        zone_origin: Name
    ) -> Box<Future<Item = Message, Error = ClientError>>
    where
        C: IntoRecordSet,
        N: IntoRecordSet,
    { ... }

    fn delete_by_rdata<R>(
        &mut self, 
        rrset: R, 
        zone_origin: Name
    ) -> Box<Future<Item = Message, Error = ClientError>>
    where
        R: IntoRecordSet,
    { ... }

    fn delete_rrset(
        &mut self, 
        record: Record, 
        zone_origin: Name
    ) -> Box<Future<Item = Message, Error = ClientError>> { ... }

    fn delete_all(
        &mut self, 
        name_of_records: Name, 
        zone_origin: Name, 
        dns_class: DNSClass
    ) -> Box<Future<Item = Message, Error = ClientError>> { ... }
}

A trait for implementing high level functions of DNS.

Required Methods

Send a message via the channel in the client

Arguments

  • message - the fully constructed Message to send, note that most implementations of will most likely be required to rewrite the QueryId, do no rely on that as being stable.

Provided Methods

A classic DNS query

Note As of now, this will not recurse on PTR or CNAME record responses, that is up to the caller.

Arguments

  • name - the label to lookup
  • query_class - most likely this should always be DNSClass::IN
  • query_type - record type to lookup

Sends a NOTIFY message to the remote system

RFC 1996, DNS NOTIFY, August 1996

1. Rationale and Scope

  1.1. Slow propagation of new and changed data in a DNS zone can be
  due to a zone's relatively long refresh times.  Longer refresh times
  are beneficial in that they reduce load on the master servers, but
  that benefit comes at the cost of long intervals of incoherence among
  authority servers whenever the zone is updated.

  1.2. The DNS NOTIFY transaction allows master servers to inform slave
  servers when the zone has changed -- an interrupt as opposed to poll
  model -- which it is hoped will reduce propagation delay while not
  unduly increasing the masters' load.  This specification only allows
  slaves to be notified of SOA RR changes, but the architechture of
  NOTIFY is intended to be extensible to other RR types.

  1.3. This document intentionally gives more definition to the roles
  of "Master," "Slave" and "Stealth" servers, their enumeration in NS
  RRs, and the SOA MNAME field.  In that sense, this document can be
  considered an addendum to [RFC1035].

The below section describes how the Notify message should be constructed. The function implmentation accepts a Record, but the actual data of the record should be ignored by the server, i.e. the server should make a request subsequent to receiving this Notification for the authority record, but could be used to decide to request an update or not:

  3.7. A NOTIFY request has QDCOUNT>0, ANCOUNT>=0, AUCOUNT>=0,
  ADCOUNT>=0.  If ANCOUNT>0, then the answer section represents an
  unsecure hint at the new RRset for this <QNAME,QCLASS,QTYPE>.  A
  slave receiving such a hint is free to treat equivilence of this
  answer section with its local data as a "no further work needs to be
  done" indication.  If ANCOUNT=0, or ANCOUNT>0 and the answer section
  differs from the slave's local data, then the slave should query its
  known masters to retrieve the new data.

Client's should be ready to handle, or be aware of, a server response of NOTIMP:

  3.12. If a NOTIFY request is received by a slave who does not
  implement the NOTIFY opcode, it will respond with a NOTIMP
  (unimplemented feature error) message.  A master server who receives
  such a NOTIMP should consider the NOTIFY transaction complete for
  that slave.

Arguments

  • name - the label which is being notified
  • query_class - most likely this should always be DNSClass::IN
  • query_type - record type which has been updated
  • rrset - the new version of the record(s) being notified

Sends a record to create on the server, this will fail if the record exists (atomicity depends on the server)

RFC 2136, DNS Update, April 1997

 2.4.3 - RRset Does Not Exist

  No RRs with a specified NAME and TYPE (in the zone and class denoted
  by the Zone Section) can exist.

  For this prerequisite, a requestor adds to the section a single RR
  whose NAME and TYPE are equal to that of the RRset whose nonexistence
  is required.  The RDLENGTH of this record is zero (0), and RDATA
  field is therefore empty.  CLASS must be specified as NONE in order
  to distinguish this condition from a valid RR whose RDLENGTH is
  naturally zero (0) (for example, the NULL RR).  TTL must be specified
  as zero (0).

2.5.1 - Add To An RRset

   RRs are added to the Update Section whose NAME, TYPE, TTL, RDLENGTH
   and RDATA are those being added, and CLASS is the same as the zone
   class.  Any duplicate RRs will be silently ignored by the primary
   master.

Arguments

  • rrset - the record(s) to create
  • zone_origin - the zone name to update, i.e. SOA name

The update must go to a zone authority (i.e. the server used in the ClientConnection)

Appends a record to an existing rrset, optionally require the rrset to exis (atomicity depends on the server)

RFC 2136, DNS Update, April 1997

2.4.1 - RRset Exists (Value Independent)

  At least one RR with a specified NAME and TYPE (in the zone and class
  specified in the Zone Section) must exist.

  For this prerequisite, a requestor adds to the section a single RR
  whose NAME and TYPE are equal to that of the zone RRset whose
  existence is required.  RDLENGTH is zero and RDATA is therefore
  empty.  CLASS must be specified as ANY to differentiate this
  condition from that of an actual RR whose RDLENGTH is naturally zero
  (0) (e.g., NULL).  TTL is specified as zero (0).

2.5.1 - Add To An RRset

   RRs are added to the Update Section whose NAME, TYPE, TTL, RDLENGTH
   and RDATA are those being added, and CLASS is the same as the zone
   class.  Any duplicate RRs will be silently ignored by the primary
   master.

Arguments

  • rrset - the record(s) to append to an RRSet
  • zone_origin - the zone name to update, i.e. SOA name
  • must_exist - if true, the request will fail if the record does not exist

The update must go to a zone authority (i.e. the server used in the ClientConnection). If the rrset does not exist and must_exist is false, then the RRSet will be created.

Compares and if it matches, swaps it for the new value (atomicity depends on the server)

 2.4.2 - RRset Exists (Value Dependent)

  A set of RRs with a specified NAME and TYPE exists and has the same
  members with the same RDATAs as the RRset specified here in this
  section.  While RRset ordering is undefined and therefore not
  significant to this comparison, the sets be identical in their
  extent.

  For this prerequisite, a requestor adds to the section an entire
  RRset whose preexistence is required.  NAME and TYPE are that of the
  RRset being denoted.  CLASS is that of the zone.  TTL must be
  specified as zero (0) and is ignored when comparing RRsets for
  identity.

 2.5.4 - Delete An RR From An RRset

  RRs to be deleted are added to the Update Section.  The NAME, TYPE,
  RDLENGTH and RDATA must match the RR being deleted.  TTL must be
  specified as zero (0) and will otherwise be ignored by the primary
  master.  CLASS must be specified as NONE to distinguish this from an
  RR addition.  If no such RRs exist, then this Update RR will be
  silently ignored by the primary master.

 2.5.1 - Add To An RRset

  RRs are added to the Update Section whose NAME, TYPE, TTL, RDLENGTH
  and RDATA are those being added, and CLASS is the same as the zone
  class.  Any duplicate RRs will be silently ignored by the primary
  master.

Arguements

  • current - the current rrset which must exist for the swap to complete
  • new - the new rrset with which to replace the current rrset
  • zone_origin - the zone name to update, i.e. SOA name

The update must go to a zone authority (i.e. the server used in the ClientConnection).

Deletes a record (by rdata) from an rrset, optionally require the rrset to exist.

RFC 2136, DNS Update, April 1997

2.4.1 - RRset Exists (Value Independent)

  At least one RR with a specified NAME and TYPE (in the zone and class
  specified in the Zone Section) must exist.

  For this prerequisite, a requestor adds to the section a single RR
  whose NAME and TYPE are equal to that of the zone RRset whose
  existence is required.  RDLENGTH is zero and RDATA is therefore
  empty.  CLASS must be specified as ANY to differentiate this
  condition from that of an actual RR whose RDLENGTH is naturally zero
  (0) (e.g., NULL).  TTL is specified as zero (0).

2.5.4 - Delete An RR From An RRset

  RRs to be deleted are added to the Update Section.  The NAME, TYPE,
  RDLENGTH and RDATA must match the RR being deleted.  TTL must be
  specified as zero (0) and will otherwise be ignored by the primary
  master.  CLASS must be specified as NONE to distinguish this from an
  RR addition.  If no such RRs exist, then this Update RR will be
  silently ignored by the primary master.

Arguments

  • rrset - the record(s) to delete from a RRSet, the name, type and rdata must match the record to delete
  • zone_origin - the zone name to update, i.e. SOA name
  • signer - the signer, with private key, to use to sign the request

The update must go to a zone authority (i.e. the server used in the ClientConnection). If the rrset does not exist and must_exist is false, then the RRSet will be deleted.

Deletes an entire rrset, optionally require the rrset to exist.

RFC 2136, DNS Update, April 1997

2.4.1 - RRset Exists (Value Independent)

  At least one RR with a specified NAME and TYPE (in the zone and class
  specified in the Zone Section) must exist.

  For this prerequisite, a requestor adds to the section a single RR
  whose NAME and TYPE are equal to that of the zone RRset whose
  existence is required.  RDLENGTH is zero and RDATA is therefore
  empty.  CLASS must be specified as ANY to differentiate this
  condition from that of an actual RR whose RDLENGTH is naturally zero
  (0) (e.g., NULL).  TTL is specified as zero (0).

2.5.2 - Delete An RRset

  One RR is added to the Update Section whose NAME and TYPE are those
  of the RRset to be deleted.  TTL must be specified as zero (0) and is
  otherwise not used by the primary master.  CLASS must be specified as
  ANY.  RDLENGTH must be zero (0) and RDATA must therefore be empty.
  If no such RRset exists, then this Update RR will be silently ignored
  by the primary master.

Arguments

  • record - The name, class and record_type will be used to match and delete the RecordSet
  • zone_origin - the zone name to update, i.e. SOA name

The update must go to a zone authority (i.e. the server used in the ClientConnection). If the rrset does not exist and must_exist is false, then the RRSet will be deleted.

Deletes all records at the specified name

RFC 2136, DNS Update, April 1997

2.5.3 - Delete All RRsets From A Name

  One RR is added to the Update Section whose NAME is that of the name
  to be cleansed of RRsets.  TYPE must be specified as ANY.  TTL must
  be specified as zero (0) and is otherwise not used by the primary
  master.  CLASS must be specified as ANY.  RDLENGTH must be zero (0)
  and RDATA must therefore be empty.  If no such RRsets exist, then
  this Update RR will be silently ignored by the primary master.

Arguments

  • name_of_records - the name of all the record sets to delete
  • zone_origin - the zone name to update, i.e. SOA name
  • dns_class - the class of the SOA

The update must go to a zone authority (i.e. the server used in the ClientConnection). This operation attempts to delete all resource record sets the the specified name reguardless of the record type.

Implementors