Diff
Not logged in

Differences From Artifact [3fb253605a]:

To Artifact [bed61d3950]:


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
...
109
110
111
112
113
114
115
116
117
118
119
120
121
122

123
124
125
126
127
128
129
130
131

132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
...
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
...
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213

214
215
216
217
218
219
220
...
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237


238
239
240
241
242
243
244
245
246
247
248
249
250
251

252
253
254
255
256
257
258
259
260
261
262
263
264

265
266

267


268
269
270
271
272
273
274

275
276
277
278
279
280
281













282
283
284
285










286
287
288
289
290
291
292
293







294
295
296

297
298

299
300
301
302
303
304
305
306
307




308
309
310
311
312
313
314

315
316
317
318
319
320



321
322
323
324
325
326
327
...
329
330
331
332
333
334
335

336
337
338
339
340
341
342

343
344

345
346
347
348
349
350
351
...
352
353
354
355
356
357
358
359

360
361
362
363
364
365
366
...
370
371
372
373
374
375
376
377


378
379
380
381
382
383
384
...
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
...
429
430
431
432
433
434
435
436

437
438
439
440
441
442
443
444
445
446
...
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
...
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506

507
508
509









































510
511




512
513

514
515
516
517

518
519
520
521
522
523
524
525
526
527
528
529
530
531

532
533

534
535
536
537
538
539













540
541
542

543
544
545
546
547
548
549
550
551
552
553
554
555
556
557

558



559
560
561
562
563
564






565
566
567
568
569
570





571
572
573
574
575
576
577
578







579






580
581
582
583
584
585
586
587








588
589
590
591
592
593
594
595
596
597
598
599
600
...
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638

639
640
641
642
643
644
645
646
647
648
649
650
651

652
653
654
655
656
657
658
659
660





661
662
663
664
665
666

667
668
669
670
671
672
673
674
675
676
677
678
679
680
681


682
683
684
685
686
687
688

689



690

691
692
693
694
695
696
697
698
699


700
701




702
703
704
705
706
707
708
709
710
711
712
713


714
715

716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
...
790
791
792
793
794
795
796

797
798
799
800
801
802
803
804
805


806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
...
834
835
836
837
838
839
840
841


842
843
844
845
846
847
848
...
855
856
857
858
859
860
861


862

863
864
865
866

867
868
869
870
871
872
873
874
875









876
877
878
879

880
881
882

883
884
885
886
887
888
889
890

891




892
893
894
895
896
897
898
899
900
901
902
903
904
905
906





907
908
909
910
911
912
913
914
915
916
917

918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942



943
944
945


946
947
948
949
950

951
952
953




954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973


974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995

996
997
998
999
1000
1001
1002
....
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
....
1063
1064
1065
1066
1067
1068
1069


1070
1071
1072
1073


1074

1075
1076
1077
1078
1079
1080
1081
....
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112

1113
1114
1115
1116
1117
1118

1119
1120
1121
1122
1123
1124
1125
....
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154



1155
1156
1157
1158
1159
1160
1161
1162
1163

1164
1165
1166
1167
1168
1169
1170

1171
1172
1173
1174
1175
1176
1177
....
1190
1191
1192
1193
1194
1195
1196
1197

1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
....
1213
1214
1215
1216
1217
1218
1219
1220

1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235

1236
1237
1238

1239
1240
1241
1242


1243
1244
1245
1246
1247
1248
1249
1250
....
1253
1254
1255
1256
1257
1258
1259
1260

1261
1262
1263

1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274

1275
1276
1277

1278
1279
1280
1281
1282


1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
....
1315
1316
1317
1318
1319
1320
1321
1322

1323

1324
1325
1326
1327
1328
1329
1330
....
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
....
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388

1389






1390
1391




1392
1393
1394

1395
1396
1397

1398
1399
1400





















































1401
1402


1403
1404
// Copyright 2016 MaidSafe.net limited.
//
// This SAFE Network Software is licensed to you under (1) the MaidSafe.net Commercial License,
// version 1.0 or later, or (2) The General Public License (GPL), version 3, depending on which
// licence you accepted on initial access to the Software (the "Licences").
//
// By contributing code to the SAFE Network Software, or to this project generally, you agree to be
// bound by the terms of the MaidSafe Contributor Agreement, version 1.1.  This, along with the
// Licenses can be found in the root directory of this project at LICENSE, COPYING and CONTRIBUTOR.
//
// Unless required by applicable law or agreed to in writing, the SAFE Network Software distributed
// under the GPL Licence is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.
//
// Please review the Licences for the specific language governing permissions and limitations
// relating to use of the SAFE Network Software.
................................................................................

mod authority;
mod error;
mod network_tests;
mod prefix;
mod xorable;

use itertools::Itertools;
pub use self::authority::Authority;
pub use self::error::Error;
#[cfg(any(test, feature = "use-mock-crust"))]
pub use self::network_tests::verify_network_invariant;
pub use self::prefix::Prefix;
pub use self::xorable::Xorable;

use std::{iter, mem};
use std::cmp::Ordering;
use std::collections::{BTreeMap, BTreeSet, btree_map, btree_set};
use std::collections::btree_map::Entry;
use std::fmt::{Binary, Debug, Formatter};
use std::fmt::Result as FmtResult;
use std::hash::Hash;

pub type Sections<T> = BTreeMap<Prefix<T>, BTreeSet<T>>;


type MemberIter<'a, T> = btree_set::Iter<'a, T>;
type SectionIter<'a, T> = btree_map::Values<'a, Prefix<T>, BTreeSet<T>>;
type OtherSectionsIter<'a, T> = iter::FlatMap<SectionIter<'a, T>,
                                              MemberIter<'a, T>,
                                              FlatMapFn<'a, T>>;
type FlatMapFn<'a, T> = fn(&'a BTreeSet<T>) -> MemberIter<'a, T>;

// Amount added to `min_section_size` when deciding whether a bucket split can happen.  This helps
// protect against rapid splitting and merging in the face of moderate churn.
const SPLIT_BUFFER: usize = 3;

// Immutable iterator over the entries of a `RoutingTable`.
pub struct Iter<'a, T: 'a + Binary + Clone + Copy + Default + Hash + Xorable> {
    inner: iter::Chain<OtherSectionsIter<'a, T>, btree_set::Iter<'a, T>>,
    our_name: T,
}

impl<'a, T: 'a + Binary + Clone + Copy + Default + Hash + Xorable> Iterator for Iter<'a, T> {
    type Item = &'a T;

    #[cfg_attr(feature="cargo-clippy", allow(while_let_on_iterator))]
................................................................................
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }
}


// Used when removal of a contact triggers the need to merge two or more sections.  Sent between all
// members of all merging sections, but not peers outwith the new section. Contains all sections in
// the routing table of nodes with the sender prefix.
#[derive(Clone, Debug, PartialEq)]
pub struct OwnMergeDetails<T: Binary + Clone + Copy + Default + Hash + Xorable> {
    pub sender_prefix: Prefix<T>,
    pub merge_prefix: Prefix<T>,
    pub sections: Sections<T>,
}



// Used once merging our own section has completed to send to peers outwith the new section
#[derive(Clone, Debug, PartialEq)]
pub struct OtherMergeDetails<T: Binary + Clone + Copy + Default + Hash + Xorable> {
    pub prefix: Prefix<T>,
    pub section: BTreeSet<T>,
}



// Details returned by a successful `RoutingTable::remove()`.
#[derive(Debug)]
pub struct RemovalDetails<T: Binary + Clone + Copy + Default + Hash + Xorable> {
    // Peer name
    pub name: T,
................................................................................
    pub was_in_our_section: bool,
}



// Details returned by `RoutingTable::merge_own_section()`.
pub enum OwnMergeState<T: Binary + Clone + Copy + Default + Hash + Xorable> {
    // If an ongoing merge is happening, and this call to `merge_own_section()` doesn't complete the
    // merge (i.e. at least one of the merging sections hasn't yet sent us its merge details), then
    // `Ongoing` is returned, implying that no further action by the caller is required.
    Ongoing,
    // If an ongoing merge is happening, and this call to `merge_own_section()` completes the merge
    // (i.e. all merging sections have sent us their merge details), then `Completed` is returned,
    // containing the appropriate targets (the `Prefix`es of all sections outwith the merging ones)
    // and the merge details they each need to receive (the new prefix and merged section).
    Completed {
        targets: BTreeSet<Prefix<T>>,
        merge_details: OtherMergeDetails<T>,

    },
    // The merge has already completed, implying that no further action by the caller is required.
    AlreadyMerged,
}



................................................................................
/// It maintains a list of sections (identified by a `Prefix<T>`), each with a
/// list node identifiers of type `T` (e.g. `XorName`) representing connected
/// peer nodes, and provides algorithms for routing messages.
///
/// See the [crate documentation](index.html) for details.
#[derive(Clone, Eq, PartialEq)]
pub struct RoutingTable<T: Binary + Clone + Copy + Debug + Default + Hash + Xorable> {
    // Minimum number of nodes we consider acceptable in a section
    min_section_size: usize,
    // Name of node holding this table
    our_name: T,
    // Prefix of our section
    our_prefix: Prefix<T>,
    // Members of our section, including our own name
    our_section: BTreeSet<T>,


    // Other sections (excludes our own) (TODO: rename)
    sections: Sections<T>,
}

impl<T: Binary + Clone + Copy + Debug + Default + Hash + Xorable> RoutingTable<T> {
    /// Creates a new `RoutingTable`.
    pub fn new(our_name: T, min_section_size: usize) -> Self {
        let mut our_section = BTreeSet::new();
        our_section.insert(our_name);
        RoutingTable {
            our_name: our_name,
            min_section_size: min_section_size,
            our_section: our_section,
            our_prefix: Default::default(),

            sections: BTreeMap::new(),
        }
    }

    /// Adds the list of `Prefix`es as empty sections.
    ///
    /// Called once a node has been approved by its own section and is given its peers' tables.
    /// Expects the current sections to be empty.
    pub fn add_prefixes(&mut self, prefixes: Vec<Prefix<T>>) -> Result<(), Error> {
        if !self.sections.is_empty() {
            return Err(Error::InvariantViolation);
        }
        for prefix in prefixes {

            if prefix.matches(&self.our_name) {
                self.our_prefix = prefix;

            } else if self.sections.insert(prefix, BTreeSet::new()).is_some() {


                return Err(Error::InvariantViolation);
            };
        }
        // In case our section has split while we've been going through the approval process, we
        // need to assign the original members of our section to the new appropriate sections.
        let our_section = mem::replace(&mut self.our_section, BTreeSet::new());
        for name in our_section {

            if self.get_section_mut(&name).map_or(true, |section| !section.insert(name)) {
                return Err(Error::InvariantViolation);
            }
        }
        self.check_invariant(true, true)
    }














    /// Returns the `Prefix` of our section
    pub fn our_prefix(&self) -> &Prefix<T> {
        &self.our_prefix
    }











    /// Returns our own section, including our own name.
    pub fn our_section(&self) -> &BTreeSet<T> {
        &self.our_section
    }

    /// Returns the whole routing table, including our section and our name
    pub fn all_sections(&self) -> Sections<T> {







        self.sections
            .clone()
            .into_iter()

            .chain(iter::once((self.our_prefix, self.our_section.clone())))
            .collect()

    }

    /// Returns the section with the given prefix, if any (includes own name if is own section)
    pub fn section_with_prefix(&self, prefix: &Prefix<T>) -> Option<&BTreeSet<T>> {
        if *prefix == self.our_prefix {
            Some(&self.our_section)
        } else {
            self.sections.get(prefix)
        }




    }

    /// Returns the total number of entries in the routing table, excluding our own name.
    // TODO: refactor to include our name?
    pub fn len(&self) -> usize {
        self.sections.values().fold(0, |acc, section| acc + section.len()) +
        self.our_section.len() - 1

    }

    /// Is the table empty? (Returns `true` if no nodes besides our own are known;
    /// empty sections are ignored.)
    pub fn is_empty(&self) -> bool {
        self.our_section.len() == 1 && self.sections.values().all(BTreeSet::is_empty)



    }

    /// Returns the minimum section size.
    pub fn min_section_size(&self) -> usize {
        self.min_section_size
    }

................................................................................
    /// allow it to be split.
    pub fn min_split_size(&self) -> usize {
        self.min_section_size + SPLIT_BUFFER
    }

    /// Returns whether the table contains the given `name`.
    pub fn has(&self, name: &T) -> bool {

        self.get_section(name).map_or(false, |section| section.contains(name))
    }

    /// Iterates over all nodes known by the routing table, excluding our own name.
    // TODO: do we need to exclude our name?
    pub fn iter(&self) -> Iter<T> {
        let iter: fn(_) -> _ = BTreeSet::iter;

        Iter {
            inner: self.sections.values().flat_map(iter).chain(self.our_section.iter()),

            our_name: self.our_name,
        }
    }

    /// Compute an estimate of the size of the network from the size of our routing table.
    ///
    /// Return (estimate, exact), with exact = true iff we have the whole network in our
................................................................................
    /// routing table.
    pub fn network_size_estimate(&self) -> (u64, bool) {
        let known_prefixes = self.prefixes();
        let is_exact = Prefix::default().is_covered_by(known_prefixes.iter());

        // Estimated fraction of the network that we have in our RT.
        // Computed as the sum of 1 / 2^(prefix.bit_count) for all known section prefixes.
        let network_fraction: f64 = known_prefixes.iter()

            .map(|p| 1.0 / (p.bit_count() as f64).exp2())
            .sum();

        // Total size estimate = known_nodes / network_fraction
        let network_size = (self.len() + 1) as f64 / network_fraction;

        (network_size.ceil() as u64, is_exact)
................................................................................
    /// `BTreeSet`.
    pub fn other_prefixes(&self) -> BTreeSet<Prefix<T>> {
        self.sections.keys().cloned().collect()
    }

    /// Collects prefixes of all sections known by the routing table into a `BTreeSet`.
    pub fn prefixes(&self) -> BTreeSet<Prefix<T>> {
        self.sections.keys().cloned().chain(iter::once(self.our_prefix)).collect()


    }

    /// If our section is the closest one to `name`, returns all names in our section *including
    /// ours*, otherwise returns `None`.
    pub fn close_names(&self, name: &T) -> Option<BTreeSet<T>> {
        if self.our_prefix.matches(name) {
            Some(self.our_section().clone())
................................................................................
    }

    /// Are we among the `count` closest nodes to `name`?
    pub fn is_closest(&self, name: &T, count: usize) -> bool {
        self.closest_names(name, count).is_some()
    }

    // Finds the `count` names closest to `name` in the whole routing table
    fn closest_known_names(&self, name: &T, count: usize) -> Vec<&T> {
        self.sections
            .iter()
            .chain(iter::once((&self.our_prefix, &self.our_section)))
            .sorted_by(|&(pfx0, _), &(pfx1, _)| pfx0.cmp_distance(pfx1, name))
            .into_iter()
            .flat_map(|(_, section)| {
                section.iter().sorted_by(|name0, name1| name.cmp_distance(name0, name1))
            })
            .take(count)
            .collect_vec()
    }

    /// Returns the `count` closest entries to `name` in the routing table, including our own name,
    /// sorted by ascending distance to `name`. If we are not close, returns `None`.
    pub fn closest_names(&self, name: &T, count: usize) -> Option<Vec<&T>> {
        let result = self.closest_known_names(name, count);
        if result.contains(&&self.our_name) {
            Some(result)
        } else {
................................................................................
        }
    }

    /// Returns the `count-1` closest entries to `name` in the routing table, excluding
    /// our own name, sorted by ascending distance to `name` -  or `None`, if our name
    /// isn't among `count` names closest to `name`.
    pub fn other_closest_names(&self, name: &T, count: usize) -> Option<Vec<&T>> {
        self.closest_names(name, count).map(|mut result| {

            result.retain(|name| *name != &self.our_name);
            result
        })
    }

    /// Returns true if `name` is in our section (including if it is our own name).
    pub fn is_in_our_section(&self, name: &T) -> bool {
        self.our_section.contains(name)
    }

................................................................................
                Ok(())
            }
        } else {
            Err(Error::PeerNameUnsuitable)
        }
    }

    /// Returns `Err(Error::PeerNameUnsuitable)` if `name` is not within our section, or
    /// `Err(Error::AlreadyExists)` if `name` is already in our table.
    pub fn should_join_our_section(&self, name: &T) -> Result<(), Error> {
        if !self.our_prefix.matches(name) {
            return Err(Error::PeerNameUnsuitable);
        }
        if self.our_section.contains(name) {
            return Err(Error::AlreadyExists);
        }
        Ok(())
    }

    /// Validates a joining node's name.
    pub fn validate_joining_node(&self, name: &T) -> Result<(), Error> {
        if !self.our_prefix.matches(name) {
            return Err(Error::PeerNameUnsuitable);
        }
        if self.our_section.contains(name) {
            return Err(Error::AlreadyExists);
................................................................................
        }
        Ok(())
    }

    /// Adds a contact to the routing table.
    ///
    /// Returns `Err` if `name` already existed in the routing table, or it doesn't fall within any
    /// of our sections, or it's our own name.  Otherwise it returns `Ok(true)` if the addition
    /// succeeded and should cause our section to split or `Ok(false)` if the addition succeeded and
    /// shouldn't cause a split.
    pub fn add(&mut self, name: T, want_to_merge: bool) -> Result<bool, Error> {
        if name == self.our_name {
            return Err(Error::OwnNameDisallowed);
        }

        if let Some(section) = self.get_section_mut(&name) {
            if !section.insert(name) {
                return Err(Error::AlreadyExists);
            }
        } else {
            return Err(Error::PeerNameUnsuitable);
        }


        let split_size = self.min_split_size();
        let close_to_merging_with_us = |(prefix, section): (&Prefix<T>, &BTreeSet<T>)| {









































            prefix.popped().is_compatible(&self.our_prefix) && section.len() < split_size
        };




        // If we're currently merging or are close to merging, we shouldn't split.
        if want_to_merge || self.sections.iter().any(close_to_merging_with_us) {

            return Ok(false);
        }

        // Count the number of names which will end up in each new section if our section is split.

        let new_size = self.our_section
            .iter()
            .filter(|name| self.our_name.common_prefix(name) > self.our_prefix.bit_count())
            .count();
        // If either of the two new sections will not contain enough entries, return `false`.
        Ok(new_size >= split_size && self.our_section().len() >= split_size + new_size)
    }

    /// Splits a section.
    ///
    /// If the section exists in the routing table, it is split, otherwise this function is a no-op.
    /// If any of the sections don't satisfy the invariant any more (i.e. only differ in one bit
    /// from our own prefix), they are removed and those contacts are returned.  If the split is
    /// happening to our own section, our new prefix is returned in the optional field.

    pub fn split(&mut self, prefix: Prefix<T>) -> (Vec<T>, Option<Prefix<T>>) {
        let mut result = vec![];

        if prefix == self.our_prefix {
            result = self.split_our_section();
            return (result, Some(self.our_prefix));
        }

        if let Some(to_split) = self.sections.remove(&prefix) {













            let prefix0 = prefix.pushed(false);
            let prefix1 = prefix.pushed(true);
            let (section0, section1) = to_split.into_iter()

                .partition::<BTreeSet<_>, _>(|name| prefix0.matches(name));

            for (pfx, section) in vec![(prefix0, section0), (prefix1, section1)] {
                if self.our_prefix.is_neighbour(&pfx) {
                    self.insert_new_section(pfx, section);
                } else {
                    result.extend(section);
                }
            }
        }
        (result, None)
    }

    /// Adds the given prefix to the routing table, merging or splitting if necessary. Returns the
    /// entries that have been dropped.

    pub fn add_prefix(&mut self, prefix: Prefix<T>) -> Vec<T> {



        let mut result = vec![];
        if self.our_prefix == prefix || self.sections.contains_key(&prefix) {
            return result; // We already have this section: Nothing to do!
        }
        // While `prefix` extends an existing entry, split that entry.
        while let Some(&shorter_pfx) =






            self.sections
                .keys()
                .chain(iter::once(&self.our_prefix))
                .find(|p| p.is_compatible(&prefix) && p.bit_count() < prefix.bit_count()) {
            let (dropped_nodes, _opt_our_pfx) = self.split(shorter_pfx);
            result.extend(dropped_nodes);





        }

        // If it's neither our neighbour nor compatible, we need to merge our own until it is
        // compatible.
        let mut our_prefix = self.our_prefix;
        while !our_prefix.is_neighbour(&prefix) && !our_prefix.is_compatible(&prefix) {
            our_prefix = our_prefix.popped();
        }







        self.merge(&our_prefix);







        // Merge if necessary, then add empty sections to satisfy the requirement that for each `i`,
        // the own prefix with the `i`-th bit flipped must be covered. To do this, split each such
        // prefix recursively until all its parts are either covered or incompatible with the
        // existing ones. Insert the incompatible ones to cover the required part of the name space.
        self.merge(&prefix);
        self.add_missing_prefixes();
        result








    }

    /// Removes a contact from the routing table.
    ///
    /// If no entry with that name is found, `Err(Error::NoSuchPeer)` is returned.  Otherwise, the
    /// entry is removed from the routing table and `RemovalDetails` is returned.  See that struct's
    /// docs for further info.
    pub fn remove(&mut self, name: &T) -> Result<RemovalDetails<T>, Error> {
        let removal_details = RemovalDetails {
            name: *name,
            was_in_our_section: self.our_prefix.matches(name),
        };
        if removal_details.was_in_our_section {
................................................................................
            if self.our_name == *name {
                return Err(Error::OwnNameDisallowed);
            }
            if !self.our_section.remove(name) {
                return Err(Error::NoSuchPeer);
            }
        } else if let Some(prefix) = self.find_section_prefix(name) {
            if let Some(section) = self.sections.get_mut(&prefix) {
                if !section.remove(name) {
                    return Err(Error::NoSuchPeer);
                }
            }
        } else {
            return Err(Error::NoSuchPeer);
        }
        Ok(removal_details)
    }

    /// If our section is required to merge, returns the details to initiate merging.
    ///
    /// Merging is required if any section has dropped below the minimum size and can only restore
    /// it by ultimately merging with us.
    ///
    /// However, merging happens in simple steps, each of which involves only two sections. If. e.g.
    /// section `1` drops below the minimum size, and the other sections are `01`, `001` and `000`,
    /// then this will return `true` only in the latter two. Once they are merged and have
    /// established all their new connections, it will return `true` in `01` and `00`. Only after
    /// that, the section `0` will merge with section `1`.
    pub fn should_merge(&self,
                        we_want_to_merge: bool,
                        they_want_to_merge: bool)
                        -> Option<OwnMergeDetails<T>> {
        let bit_count = self.our_prefix.bit_count();
        let doesnt_need_to_merge_with_us = |(prefix, section): (&Prefix<T>, &BTreeSet<T>)| {
            !prefix.popped().is_compatible(&self.our_prefix) ||
            section.len() >= self.min_section_size
        };
        if bit_count == 0 || we_want_to_merge ||

           !self.sections.contains_key(&self.our_prefix.with_flipped_bit(bit_count - 1)) {
            return None; // We can't merge, or we already sent our merge message.
        }
        if !they_want_to_merge && self.our_section.len() >= self.min_section_size &&
           self.sections.iter().all(doesnt_need_to_merge_with_us) {
            return None; // There is no reason to merge.
        }
        let merge_prefix = self.our_prefix.popped();
        Some(OwnMergeDetails {
            sender_prefix: self.our_prefix,
            merge_prefix: merge_prefix,
            sections: self.all_sections(),
        })

    }

    /// When a merge of our own section is triggered (either from our own section or a neighbouring
    /// one) this function handles the incoming merge details from the peers within the merging
    /// sections.
    ///
    /// The actual merge of the section is only done once all expected merging sections have
    /// provided details.  See the docs for `OwnMergeState` for full details of the return value.
    pub fn merge_own_section(&mut self, merge_details: OwnMergeDetails<T>) -> OwnMergeState<T> {





        // TODO: Return an error if they are not compatible instead?
        if !self.our_prefix.is_compatible(&merge_details.merge_prefix) ||
           self.our_prefix.bit_count() != merge_details.merge_prefix.bit_count() + 1 {
            debug!("{:?}: Attempt to call merge_own_section() for an already merged prefix {:?}",
                   self.our_name,
                   merge_details.merge_prefix);

            return OwnMergeState::AlreadyMerged;
        }
        for prefix in merge_details.sections.keys() {
            if *prefix == self.our_prefix || self.sections.contains_key(prefix) {
                continue; // Already in our routing table.
            } else if self.our_prefix.is_compatible(prefix) ||
                      self.sections.keys().any(|pfx| prefix.is_compatible(pfx)) {
                error!("{:?} Received unsuitable prefix {:?} in OwnSectionMerge.",
                       self.our_name,
                       prefix);
            } else {
                self.insert_new_section(*prefix, BTreeSet::new());
            }
        }



        // We currently handle this first for our own section, then for the sibling.
        // TODO: Pass all merge details in and handle them at once. Remove `Ongoing` state.
        if merge_details.sender_prefix != self.our_prefix {
            // We've heard from all merging sections - do the merge and return `Completed`.
            self.finish_merging_own_section(merge_details.merge_prefix)
        } else {
            // We don't have the merge details from both sides yet.

            OwnMergeState::Ongoing



        }

    }

    /// Merges all existing compatible sections into the new one defined by `merge_details.prefix`.
    /// Our own section is not included in the merge.
    ///
    /// The appropriate targets (all contacts from `merge_details.sections` which are not currently
    /// held in the routing table) are returned so the caller can establish connections to these
    /// peers and subsequently add them.
    pub fn merge_other_section(&mut self, merge_details: OtherMergeDetails<T>) -> BTreeSet<T> {


        if self.our_prefix.is_compatible(&merge_details.prefix) {
            // We've already handled this particular merge via `merge_own_section()`.




            return BTreeSet::new();
        }

        let should_merge = |prefix: &Prefix<T>| {
            prefix.is_compatible(&merge_details.prefix) &&
            prefix.bit_count() > merge_details.prefix.bit_count()
        };

        if self.sections.keys().any(should_merge) {
            self.merge(&merge_details.prefix);
            // Establish list of provided contacts which are currently missing from our table.
            merge_details.section


                .difference(unwrap!(self.sections.get(&merge_details.prefix)))
                .cloned()

                .collect()
        } else {
            // We've already handled this particular merge.
            BTreeSet::new()
        }
    }

    /// Returns a collection of nodes to which a message for the given `Authority` should be sent
    /// onwards.  In all non-error cases below, the returned collection will have the members of
    /// `exclude` removed, possibly resulting in an empty set being returned.
    ///
    /// * If the destination is an `Authority::Section`:
    ///     - if our section is the closest on the network (i.e. our section's prefix is a prefix of
    ///       the destination), returns all other members of our section; otherwise
    ///     - returns the `route`-th closest member of the RT to the target
    ///
................................................................................
            }
            Authority::PrefixSection(ref prefix) => {
                if prefix.is_compatible(&self.our_prefix) {
                    // only route the message when we have all the targets in our routing table -
                    // this is to prevent spamming the network by sending messages with
                    // intentionally short prefixes
                    if prefix.is_covered_by(self.prefixes().iter()) {

                        let is_compatible = |(pfx, section)| if prefix.is_compatible(pfx) {
                            Some(section)
                        } else {
                            None
                        };
                        return Ok(self.sections
                            .iter()
                            .filter_map(is_compatible)
                            .flat_map(BTreeSet::iter)


                            .chain(self.our_section.iter().filter(|name| **name != self.our_name))
                            .cloned()
                            .collect());
                    } else {
                        return Err(Error::CannotRoute);
                    }
                }
                candidates(&prefix.lower_bound())
            }
        };
        Ok(iter::once(self.get_routeth_node(&closest_section, dst.name(), Some(exclude), route)?)
            .collect())
    }

    /// Returns whether we are a part of the given authority.
    pub fn in_authority(&self, auth: &Authority<T>) -> bool {
        match *auth {
            // clients have no routing tables
            Authority::Client { .. } => false,
................................................................................
    /// Returns the section matching the given `name`, if present.
    /// Includes our own name in the case that our prefix matches `name`.
    pub fn get_section(&self, name: &T) -> Option<&BTreeSet<T>> {
        if self.our_prefix.matches(name) {
            return Some(&self.our_section);
        }
        if let Some(prefix) = self.find_section_prefix(name) {
            return self.sections.get(&prefix);


        }
        None
    }

    /// Returns our name.
    pub fn our_name(&self) -> &T {
        &self.our_name
................................................................................

    /// Returns the prefix of the section in which `name` belongs, or `None` if there is no such
    /// section in the routing table.
    pub fn find_section_prefix(&self, name: &T) -> Option<Prefix<T>> {
        if self.our_prefix.matches(name) {
            return Some(self.our_prefix);
        }


        self.sections.keys().find(|&prefix| prefix.matches(name)).cloned()

    }

    /// Returns `name` modified so that it belongs to one of the known prefixes with minimal bit
    /// length, favouring our own prefix if it is one of the shortest.

    pub fn assign_to_min_len_prefix(&self, name: &T) -> T {
        let target_prefix = iter::once(&self.our_prefix)
            .chain(self.sections.keys())
            .min_by_key(|prefix| prefix.bit_count())
            .unwrap_or(&self.our_prefix);
        target_prefix.substituted_in(*name)
    }

    fn split_our_section(&mut self) -> Vec<T> {









        let next_bit = self.our_name.bit(self.our_prefix.bit_count());
        let other_prefix = self.our_prefix.pushed(!next_bit);
        self.our_prefix = self.our_prefix.pushed(next_bit);
        let (our_new_section, other_section) = self.our_section

            .iter()
            .partition::<BTreeSet<_>, _>(|name| self.our_prefix.matches(name));
        self.our_section = our_new_section;

        // Drop sections that ceased to be our neighbours.
        let sections_to_remove = self.sections
            .keys()
            .filter(|prefix| !prefix.is_neighbour(&self.our_prefix))
            .cloned()
            .collect_vec();
        self.insert_new_section(other_prefix, other_section);
        sections_to_remove.into_iter()

            .filter_map(|prefix| self.sections.remove(&prefix))




            .flat_map(BTreeSet::into_iter)
            .collect()
    }

    /// Inserts the given section. Logs an error if it already exists.
    fn insert_new_section(&mut self, prefix: Prefix<T>, section: BTreeSet<T>) {
        match self.sections.entry(prefix) {
            Entry::Vacant(entry) => {
                let _section_ref = entry.insert(section);
            }
            Entry::Occupied(entry) => {
                error!("{:?} Inserting section {:?}, but already has members {:?}. This is a bug!",
                       self.our_name,
                       prefix,
                       entry.get());





                entry.into_mut().extend(section);
            }
        }
    }

    fn finish_merging_own_section(&mut self, merge_prefix: Prefix<T>) -> OwnMergeState<T> {
        self.merge(&merge_prefix);
        self.add_missing_prefixes();
        // The update needs to be sent to all neighbouring sections. However, while those are
        // merging/splitting, our own section might not agree on their prefixes and the message can
        // fail to accumulate. So also include results of flipping one bit in the `merge_prefix`.

        let targets = self.sections
            .keys()
            .cloned()
            .chain((0..merge_prefix.bit_count()).map(|i| merge_prefix.with_flipped_bit(i)))
            .collect();
        let other_details = OtherMergeDetails {
            prefix: merge_prefix,
            section: self.our_section().clone(),
        };
        OwnMergeState::Completed {
            targets: targets,
            merge_details: other_details,
        }
    }

    fn merge(&mut self, new_prefix: &Prefix<T>) {
        // Partition the sections into those for merging and the rest
        let original_sections = mem::replace(&mut self.sections, Sections::new());
        let (sections_to_merge, sections) = original_sections.into_iter()
            .partition::<BTreeMap<_, _>, _>(|&(prefix, _)| new_prefix.is_compatible(&prefix));
        self.sections = sections;
        // Merge selected sections and add the merged section back in.
        let merged_names = sections_to_merge.into_iter().flat_map(|(_, names)| names).collect();
        if self.our_prefix.is_compatible(new_prefix) {
            self.our_section.extend(merged_names);



            self.our_prefix = *new_prefix;
        } else {
            self.insert_new_section(*new_prefix, merged_names);


        }
    }

    /// Inserts empty sections so that the prefixes cover all neighbouring areas of the namespace.
    fn add_missing_prefixes(&mut self) {

        let mut missing_pfxs = (0..self.our_prefix.bit_count())
            .map(|i| self.our_prefix.with_flipped_bit(i))
            .collect_vec();




        while let Some(pfx) = missing_pfxs.pop() {
            if !pfx.is_covered_by(self.sections.keys()) {
                if self.sections.keys().any(|p| pfx.is_compatible(p)) {
                    missing_pfxs.push(pfx.pushed(true));
                    missing_pfxs.push(pfx.pushed(false));
                } else {
                    self.insert_new_section(pfx, BTreeSet::new());
                }
            }
        }
    }

    /// Get a mutable reference to whichever section matches the given name. If our own section,
    /// our name is included.
    fn get_section_mut(&mut self, name: &T) -> Option<&mut BTreeSet<T>> {
        if self.our_prefix.matches(name) {
            return Some(&mut self.our_section);
        }
        if let Some(prefix) = self.find_section_prefix(name) {
            return self.sections.get_mut(&prefix);


        }
        None
    }

    /// Returns the prefix of the closest non-empty section to `name`, regardless of whether `name`
    /// belongs in that section or not, and the section itself.
    fn closest_section(&self, name: &T) -> (&Prefix<T>, &BTreeSet<T>) {
        let mut result = (&self.our_prefix, &self.our_section);
        for (prefix, section) in &self.sections {
            if !section.is_empty() && result.0.cmp_distance(prefix, name) == Ordering::Greater {
                result = (prefix, section)
            }
        }
        result
    }

    /// Gets the `route`-th name from a collection of names
    fn get_routeth_name<'a, U: IntoIterator<Item = &'a T>>(names: U,
                                                           dst_name: &T,
                                                           route: usize)
                                                           -> &'a T {
        let sorted_names = names.into_iter()

            .sorted_by(|&lhs, &rhs| dst_name.cmp_distance(lhs, rhs));
        sorted_names[route % sorted_names.len()]
    }

    /// Returns the `route`-th node in the given section, sorted by distance to `target`
    fn get_routeth_node(&self,
                        section: &BTreeSet<T>,
................................................................................
                return warn(format!("Name {} doesn't match section prefix {:?}: {:?}",
                                    name.debug_binary(),
                                    self.our_prefix,
                                    self));
            }
        }

        for (prefix, section) in &self.sections {
            if has_enough_nodes && section.len() < self.min_section_size {
                if section.len() <= 1 && allow_small_sections {
                    continue;
                }
                return warn(format!("Minimum group size not met for group {:?}: {:?}",
                                    prefix,
                                    self));
................................................................................
                                        name.debug_binary(),
                                        prefix,
                                        self));
                }
            }
        }



        let all_are_neighbours = self.sections.keys().all(|&x| self.our_prefix.is_neighbour(&x));
        let all_neighbours_covered = {
            let prefixes = self.prefixes();
            (0..self.our_prefix.bit_count())


                .all(|i| self.our_prefix.with_flipped_bit(i).is_covered_by(&prefixes))

        };
        if !all_are_neighbours {
            return warn(format!("Some sections in the RT aren't neighbours of our section: {:?}",
                                self));
        }
        if !all_neighbours_covered {
            return warn(format!("Some neighbours aren't fully covered by the RT: {:?}", self));
................................................................................
        writeln!(formatter, "RoutingTable {{")?;
        writeln!(formatter, "\tmin_section_size: {},", self.min_section_size)?;
        writeln!(formatter,
                 "\tour_name: {:?} ({}),",
                 self.our_name,
                 self.our_name.debug_binary())?;
        writeln!(formatter, "\tour_prefix: {:?}", self.our_prefix)?;
        let sections = self.sections
            .iter()
            .chain(iter::once((&self.our_prefix, &self.our_section)))

            .collect::<BTreeSet<_>>();
        for (section_index, &(prefix, section)) in sections.iter().enumerate() {
            write!(formatter,
                   "\tsection {} with {:?}: {{\n",
                   section_index,
                   prefix)?;

            for (name_index, name) in section.iter().enumerate() {
                let comma = if name_index == section.len() - 1 {
                    ""
                } else {
                    ","
                };
                writeln!(formatter,
................................................................................
        Binary::fmt(self, formatter)
    }
}


#[cfg(test)]
mod tests {
    use itertools::Itertools;
    use std::collections::BTreeSet;
    use super::*;
    use super::SPLIT_BUFFER;




    #[test]
    fn small() {
        let name = 123u32;
        let table = RoutingTable::new(name, 6);
        assert_eq!(*table.our_name(), name);
        assert_eq!(table.len(), 0);
        assert!(table.is_empty());
        assert_eq!(table.iter().count(), 0);

    }

    // Adds `min_split_size() - 1` entries to `table`, starting at `name` and incrementing it by 1
    // each time.
    fn add_sequential_entries(table: &mut RoutingTable<u16>, name: &mut u16) {
        for _ in 1..table.min_split_size() {
            assert_eq!(table.add(*name, false), Ok(false));

            table.verify_invariant();
            *name += 1;
        }
    }

    // Test explicitly covers `close_names()`, `other_close_names()`, `is_in_our_section()` and
    // `need_to_add()` while also implicitly testing `add()` and `split()`.
................................................................................
        let mut section_00_name = our_name + 1;
        let mut section_10_name = our_name.with_flipped_bit(0);
        add_sequential_entries(&mut table, &mut section_00_name);
        add_sequential_entries(&mut table, &mut section_10_name);
        expected_rt_len += 2 * (table.min_split_size() - 1);

        // Add one name to the other half to trigger the split to sections 0 and 1.
        assert_eq!(table.add(section_10_name, false), Ok(true));

        expected_rt_len += 1;
        let mut expected_own_prefix = Prefix::new(0, our_name);
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        let (nodes_to_drop, our_new_prefix) = table.split(expected_own_prefix);
        expected_own_prefix = Prefix::new(1, our_name);
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        assert_eq!(unwrap!(our_new_prefix), expected_own_prefix);
        assert!(nodes_to_drop.is_empty());
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);
        assert_eq!(table.all_sections().len(), 2);
................................................................................
        let mut section_01_name = our_name.with_flipped_bit(1);
        let mut section_11_name = section_10_name.with_flipped_bit(1);
        add_sequential_entries(&mut table, &mut section_01_name);
        add_sequential_entries(&mut table, &mut section_11_name);
        expected_rt_len += 2 * (table.min_split_size() - 1);

        // Trigger split in our own section first to yield sections 00, 01 and 1.
        assert_eq!(table.add(section_01_name, false), Ok(true));

        expected_rt_len += 1;
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        let (nodes_to_drop, our_new_prefix) = table.split(expected_own_prefix);
        expected_own_prefix = Prefix::new(2, our_name);
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        assert_eq!(unwrap!(our_new_prefix), expected_own_prefix);
        assert!(nodes_to_drop.is_empty());
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);
        assert_eq!(table.all_sections().len(), 3);
        assert_eq!(table.our_section().len(), table.min_split_size());

        // Now trigger split in section 1, which should cause section 11 to get ejected, leaving
        // sections 00, 01 and 10.
        assert_eq!(table.add(section_11_name, false), Ok(false));

        expected_rt_len += 1;
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        let (nodes_to_drop, our_new_prefix) = table.split(Prefix::new(1, section_11_name));

        assert_eq!(*table.our_prefix(), expected_own_prefix);
        assert!(our_new_prefix.is_none());
        assert_eq!(nodes_to_drop.len(), table.min_split_size());
        let mut drop_prefix = Prefix::new(2, section_11_name);


        assert!(nodes_to_drop.iter().all(|name| drop_prefix.matches(name)));
        expected_rt_len -= nodes_to_drop.len();
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);
        assert_eq!(table.all_sections().len(), 3);
        assert_eq!(table.our_section().len(), table.min_split_size());

        // Add `min_split_size - 1` with names 001... and names 011... to get sections 00 and 01
................................................................................
        let mut section_011_name = section_001_name.with_flipped_bit(1);
        add_sequential_entries(&mut table, &mut section_001_name);
        add_sequential_entries(&mut table, &mut section_011_name);
        expected_rt_len += 2 * (table.min_split_size() - 1);

        // Trigger split in other section (i.e. section 01) first this time to yield sections 00,
        // 010, 011 and 10.
        assert_eq!(table.add(section_011_name, false), Ok(false));

        expected_rt_len += 1;
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        let (nodes_to_drop, our_new_prefix) = table.split(Prefix::new(2, section_011_name));

        assert_eq!(*table.our_prefix(), expected_own_prefix);
        assert!(our_new_prefix.is_none());
        assert!(nodes_to_drop.is_empty());
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);
        assert_eq!(table.all_sections().len(), 4);
        assert_eq!(table.our_section().len(), 2 * table.min_split_size() - 1);

        // Now trigger split in own section (i.e. section 00), which should cause section 011 to get
        // ejected, leaving sections 000, 001, 010 and 10.
        assert_eq!(table.add(section_001_name, false), Ok(true));

        expected_rt_len += 1;
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        let (nodes_to_drop, our_new_prefix) = table.split(expected_own_prefix);

        expected_own_prefix = Prefix::new(3, our_name);
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        assert_eq!(unwrap!(our_new_prefix), expected_own_prefix);
        assert_eq!(nodes_to_drop.len(), table.min_split_size());
        drop_prefix = Prefix::new(3, section_011_name);


        assert!(nodes_to_drop.iter().all(|name| drop_prefix.matches(name)));
        expected_rt_len -= nodes_to_drop.len();
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);
        assert_eq!(table.all_sections().len(), 4);
        assert_eq!(table.our_section().len(), table.min_split_size());

        // Try to add a name which is already in the RT.
        assert_eq!(table.add(section_001_name, false),
                   Err(Error::AlreadyExists));
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);

        // Try to add our own name.
        assert_eq!(table.add(our_name, false), Err(Error::OwnNameDisallowed));
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);

        // Try to add a name which doesn't fit any section.
        assert_eq!(table.add(nodes_to_drop[0], false),
                   Err(Error::PeerNameUnsuitable));
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);

        // Check `is_in_our_section()`.
        assert!(table.is_in_our_section(&our_name));
        assert!(table.is_in_our_section(&(section_00_name - 1)));
        assert!(!table.is_in_our_section(&section_001_name));
................................................................................
        assert!(our_section.contains(&our_name));
        assert_eq!(unwrap!(table.close_names(&our_name)), our_section);
        assert_eq!(unwrap!(table.close_names(&section_00_name)), our_section);
        assert!(table.close_names(&section_001_name).is_none());
        assert!(table.close_names(&section_10_name).is_none());

        // Check `other_close_names()`.
        let our_section_without_us =

            our_section.into_iter().filter(|name| *name != our_name).collect::<BTreeSet<_>>();

        assert_eq!(unwrap!(table.other_close_names(&our_name)),
                   our_section_without_us);
        assert_eq!(unwrap!(table.other_close_names(&section_00_name)),
                   our_section_without_us);
        assert!(table.other_close_names(&section_001_name).is_none());
        assert!(table.other_close_names(&section_10_name).is_none());

................................................................................
    }

    #[test]
    fn test_closest_names() {
        let our_name = 0u16;
        let mut table = RoutingTable::new(our_name, 8);
        // initialize the table
        unwrap!(table.add(0x8000, false));
        unwrap!(table.add(0x4000, false));
        unwrap!(table.add(0x2000, false));
        unwrap!(table.add(0x1000, false));
        unwrap!(table.add(0x0800, false));
        unwrap!(table.add(0x0400, false));
        unwrap!(table.add(0x0200, false));
        unwrap!(table.add(0x0100, false));
        unwrap!(table.add(0x0080, false));
        unwrap!(table.add(0x0040, false));

        let mut name = 0xFFFF;
        assert!(table.closest_names(&name, 10).is_none());
        assert!(table.other_closest_names(&name, 10).is_none());
        assert!(table.closest_names(&name, 11).is_some());
        let result = unwrap!(table.other_closest_names(&name, 11));
        assert_eq!(result.len(), 10);
................................................................................

    #[test]
    fn test_add_prefix() {
        let our_name = 0u8;
        let mut table = RoutingTable::new(our_name, 1);
        // Add 10, 20, 30, 40, 50, 60, 70, 80, 90, A0, B0, C0, D0, E0 and F0.
        for i in 1..0x10 {
            unwrap!(table.add(i * 0x10, false));
        }
        assert_eq!(prefixes_from_strs(vec![""]), table.prefixes());
        assert_eq!(Vec::<u8>::new(), table.add_prefix(Prefix::from_str("01")));

        assert_eq!(prefixes_from_strs(vec!["1", "00", "01"]), table.prefixes());






        assert_eq!(vec![0xc0, 0xd0, 0xe0, 0xf0u8],
                   table.add_prefix(Prefix::from_str("111")).into_iter().sorted());




        assert_eq!(prefixes_from_strs(vec!["110", "111", "10", "0"]),
                   table.prefixes());
        assert_eq!(Vec::<u8>::new(), table.add_prefix(Prefix::from_str("0")));

        assert_eq!(prefixes_from_strs(vec!["110", "111", "10", "0"]),
                   table.prefixes());
        assert_eq!(Vec::<u8>::new(), table.add_prefix(Prefix::from_str("")));

        assert_eq!(prefixes_from_strs(vec![""]), table.prefixes());
    }






















































    fn prefixes_from_strs(strs: Vec<&str>) -> BTreeSet<Prefix<u8>> {
        strs.into_iter().map(Prefix::from_str).collect()


    }
}







|
|







 







<




|

>


|





|
>

<
<
<
<
<
<
<
|





|







 







<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<
<







 







<
<
<
<






|
>







 







|

|

|

|

>
>
|













>







|
|
|


|
>


>
|
>
>







>
|






>
>
>
>
>
>
>
>
>
>
>
>
>
|



>
>
>
>
>
>
>
>
>
>








>
>
>
>
>
>
>
|
<
|
>
|
<
>




|
<
<
<
|
>
>
>
>





|
|
>





|
>
>
>







 







>
|





|
>

<
>







 







|
>







 







|
>
>







 







<
<
<
<
<
<
<
<
<
<
<
<
<
<







 







|
>
|
|
|







 







<
<
<
<
<
<
<
<
<
<
<
<







 







|
<
<
|











>
|
<
<
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
|
|
>
>
>
>

<
>
|



>





|




|
|
|
|
>
|

>

|



<
>
>
>
>
>
>
>
>
>
>
>
>
>
|
|
|
>
|

|
|
|
|
|
|
|
<




|
>
|
>
>
>
|
<
<

<
<
>
>
>
>
>
>
|
<
<
<
<
<
>
>
>
>
>
|
|
<
<
<
<
<
|
>
>
>
>
>
>
>
|
>
>
>
>
>
>
|
<
<
<
<
<

<
>
>
>
>
>
>
>
>




|
|







 







|










|









|
<
<
<

<
<
<
<
<
>
|
|

<
<
<
<
<
<
<
<
<
<
>







|
|
>
>
>
>
>

|
|
|

<
>
|

<
<
<
<
<
|
|
|
|
|
|
<
<
>
>
|
|
|
|
|
|
|
>
|
>
>
>
|
>








|
>
>
|
<
>
>
>
>


<
<
<
<
<
<
<
|
|
|
>
>
|
|
>
|
<
<
<
|



|







 







>
|





|
|
|
>
>
|
|
|








|







 







|
>
>







 







>
>
|
>


<
<
>
|
|
|
|
|
<


|
>
>
>
>
>
>
>
>
>



|
>
|
|

>






|
|
>
|
>
>
>
>





|


|






>
>
>
>
>
|




<
<
<
<
<
|
>
|
|
<
|
|
<
<
<
<
<
<
<

<
<
<
<
<
<
<
<
<
<
<
<
>
>
>
|
<
<
>
>





>
|
<
<
>
>
>
>

|




|












|
>
>








|












|
>







 







|







 







>
>
|


|
>
>
|
>







 







|
<
<
>
|
|

|

|
>







 







<
<


>
>
>









>






|
>







 







|
>



|







 







|
>


|











|
>


|
>




>
>
|







 







|
>


|
>










|
>


|
>





>
>
|







|
<




|




|
<







 







|
>
|
>







 







|
|
|
|
|
|
|
|
|
|







 







|


|
>

>
>
>
>
>
>

<
>
>
>
>
|

|
>
|

|
>



>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>

|
>
>


1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
...
109
110
111
112
113
114
115

116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133







134
135
136
137
138
139
140
141
142
143
144
145
146
147
...
155
156
157
158
159
160
161




















162
163
164
165
166
167
168
...
170
171
172
173
174
175
176




177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
...
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303

304
305
306

307
308
309
310
311
312



313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
...
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359

360
361
362
363
364
365
366
367
...
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
...
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
...
419
420
421
422
423
424
425














426
427
428
429
430
431
432
...
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
...
465
466
467
468
469
470
471












472
473
474
475
476
477
478
...
479
480
481
482
483
484
485
486


487
488
489
490
491
492
493
494
495
496
497
498
499
500


501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548

549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577

578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603

604
605
606
607
608
609
610
611
612
613
614


615


616
617
618
619
620
621
622





623
624
625
626
627
628
629





630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645





646

647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
...
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696



697





698
699
700
701










702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721

722
723
724





725
726
727
728
729
730


731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758

759
760
761
762
763
764







765
766
767
768
769
770
771
772
773



774
775
776
777
778
779
780
781
782
783
784
785
...
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
...
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
...
914
915
916
917
918
919
920
921
922
923
924
925
926


927
928
929
930
931
932

933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992





993
994
995
996

997
998







999












1000
1001
1002
1003


1004
1005
1006
1007
1008
1009
1010
1011
1012


1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
....
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
....
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
....
1174
1175
1176
1177
1178
1179
1180
1181


1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
....
1215
1216
1217
1218
1219
1220
1221


1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
....
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
....
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
....
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377

1378
1379
1380
1381
1382
1383
1384
1385
1386
1387

1388
1389
1390
1391
1392
1393
1394
....
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
....
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
....
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483

1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
// Copyright 2016 MaidSafe.net limited.
//
// This SAFE Network Software is licensed to you under (1) the MaidSafe.net Commercial License,
// version 1.0 or later, or (2) The General Public License (GPL), version 3, depending on which
// licence you accepted on initial access to the Software (the "Licences").
//
// By contributing code to the SAFE Network Software, or to this project generally, you agree to be
// bound by the terms of the MaidSafe Contributor Agreement.  This, along with the Licenses can be
// found in the root directory of this project at LICENSE, COPYING and CONTRIBUTOR.
//
// Unless required by applicable law or agreed to in writing, the SAFE Network Software distributed
// under the GPL Licence is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
// KIND, either express or implied.
//
// Please review the Licences for the specific language governing permissions and limitations
// relating to use of the SAFE Network Software.
................................................................................

mod authority;
mod error;
mod network_tests;
mod prefix;
mod xorable;


pub use self::authority::Authority;
pub use self::error::Error;
#[cfg(any(test, feature = "use-mock-crust"))]
pub use self::network_tests::verify_network_invariant;
pub use self::prefix::{Prefix, VersionedPrefix};
pub use self::xorable::Xorable;
use itertools::Itertools;
use std::{iter, mem};
use std::cmp::Ordering;
use std::collections::{BTreeMap, BTreeSet};
use std::collections::btree_map::Entry;
use std::fmt::{Binary, Debug, Formatter};
use std::fmt::Result as FmtResult;
use std::hash::Hash;

pub type Sections<T> = BTreeMap<Prefix<T>, (u64, BTreeSet<T>)>;
type SectionItem<'a, T> = (Prefix<T>, (u64, &'a BTreeSet<T>));








// Amount added to `min_section_size` when deciding whether a bucket split can happen. This helps
// protect against rapid splitting and merging in the face of moderate churn.
const SPLIT_BUFFER: usize = 3;

// Immutable iterator over the entries of a `RoutingTable`.
pub struct Iter<'a, T: 'a + Binary + Clone + Copy + Default + Hash + Xorable> {
    inner: Box<Iterator<Item = &'a T> + 'a>,
    our_name: T,
}

impl<'a, T: 'a + Binary + Clone + Copy + Default + Hash + Xorable> Iterator for Iter<'a, T> {
    type Item = &'a T;

    #[cfg_attr(feature="cargo-clippy", allow(while_let_on_iterator))]
................................................................................
    }

    fn size_hint(&self) -> (usize, Option<usize>) {
        self.inner.size_hint()
    }
}























// Details returned by a successful `RoutingTable::remove()`.
#[derive(Debug)]
pub struct RemovalDetails<T: Binary + Clone + Copy + Default + Hash + Xorable> {
    // Peer name
    pub name: T,
................................................................................
    pub was_in_our_section: bool,
}



// Details returned by `RoutingTable::merge_own_section()`.
pub enum OwnMergeState<T: Binary + Clone + Copy + Default + Hash + Xorable> {




    // If an ongoing merge is happening, and this call to `merge_own_section()` completes the merge
    // (i.e. all merging sections have sent us their merge details), then `Completed` is returned,
    // containing the appropriate targets (the `Prefix`es of all sections outwith the merging ones)
    // and the merge details they each need to receive (the new prefix and merged section).
    Completed {
        targets: BTreeSet<Prefix<T>>,
        versioned_prefix: VersionedPrefix<T>,
        section: BTreeSet<T>,
    },
    // The merge has already completed, implying that no further action by the caller is required.
    AlreadyMerged,
}



................................................................................
/// It maintains a list of sections (identified by a `Prefix<T>`), each with a
/// list node identifiers of type `T` (e.g. `XorName`) representing connected
/// peer nodes, and provides algorithms for routing messages.
///
/// See the [crate documentation](index.html) for details.
#[derive(Clone, Eq, PartialEq)]
pub struct RoutingTable<T: Binary + Clone + Copy + Debug + Default + Hash + Xorable> {
    /// Minimum number of nodes we consider acceptable in a section
    min_section_size: usize,
    /// Name of node holding this table
    our_name: T,
    /// Prefix of our section
    our_prefix: Prefix<T>,
    /// Members of our section, including our own name
    our_section: BTreeSet<T>,
    /// Our prefix version.
    our_version: u64,
    /// Other sections (excludes our own) (TODO: rename)
    sections: Sections<T>,
}

impl<T: Binary + Clone + Copy + Debug + Default + Hash + Xorable> RoutingTable<T> {
    /// Creates a new `RoutingTable`.
    pub fn new(our_name: T, min_section_size: usize) -> Self {
        let mut our_section = BTreeSet::new();
        our_section.insert(our_name);
        RoutingTable {
            our_name: our_name,
            min_section_size: min_section_size,
            our_section: our_section,
            our_prefix: Default::default(),
            our_version: 0,
            sections: BTreeMap::new(),
        }
    }

    /// Adds the list of `Prefix`es as empty sections.
    ///
    /// Called once a node has been approved by its own section and is given its peers' tables.
    /// Expects the current sections to be empty and have version 0.
    pub fn add_prefixes(&mut self, ver_pfxs: Vec<VersionedPrefix<T>>) -> Result<(), Error> {
        if self.our_version != 0 || !self.sections.is_empty() {
            return Err(Error::InvariantViolation);
        }
        for ver_pfx in ver_pfxs {
            let (prefix, version) = ver_pfx.into();
            if prefix.matches(&self.our_name) {
                self.our_prefix = prefix;
                self.our_version = version;
            } else if self.sections
                          .insert(prefix, (version, BTreeSet::new()))
                          .is_some() {
                return Err(Error::InvariantViolation);
            };
        }
        // In case our section has split while we've been going through the approval process, we
        // need to assign the original members of our section to the new appropriate sections.
        let our_section = mem::replace(&mut self.our_section, BTreeSet::new());
        for name in our_section {
            if self.get_section_mut(&name)
                   .map_or(true, |section| !section.insert(name)) {
                return Err(Error::InvariantViolation);
            }
        }
        self.check_invariant(true, true)
    }

    /// Checks that the `NodeApproval` message contains a valid `RoutingTable`.
    pub fn check_node_approval_msg(&self,
                                   sections: BTreeMap<Prefix<T>, BTreeSet<T>>)
                                   -> Result<(), Error> {
        let mut temp_rt = RoutingTable::new(self.our_name, self.min_section_size);
        temp_rt
            .add_prefixes(sections.keys().map(|pfx| pfx.with_version(0)).collect())?;
        for peer in sections.values().flat_map(BTreeSet::iter) {
            let _ = temp_rt.add(*peer);
        }
        temp_rt.check_invariant(false, true)
    }

    /// Returns the `Prefix` of our section.
    pub fn our_prefix(&self) -> &Prefix<T> {
        &self.our_prefix
    }

    /// Returns the version of our section.
    pub fn our_version(&self) -> u64 {
        self.our_version
    }

    /// Returns the `VersionedPrefix` of our section.
    pub fn our_versioned_prefix(&self) -> VersionedPrefix<T> {
        self.our_prefix.with_version(self.our_version)
    }

    /// Returns our own section, including our own name.
    pub fn our_section(&self) -> &BTreeSet<T> {
        &self.our_section
    }

    /// Returns the whole routing table, including our section and our name
    pub fn all_sections(&self) -> Sections<T> {
        self.all_sections_iter()
            .map(|(p, (v, section))| (p, (v, section.clone())))
            .collect()
    }

    /// Create an iterator over all sections including our own.
    pub fn all_sections_iter<'a>(&'a self) -> Box<Iterator<Item = SectionItem<T>> + 'a> {
        let iter = self.sections

            .iter()
            .map(|(&p, &(v, ref sec))| (p, (v, sec)))
            .chain(iter::once((self.our_prefix, (self.our_version, &self.our_section))));

        Box::new(iter)
    }

    /// Returns the section with the given prefix, if any (includes own name if is own section)
    pub fn section_with_prefix(&self, prefix: &Prefix<T>) -> Option<&BTreeSet<T>> {
        self.lookup_section(prefix).map(|(_, section)| section)



    }

    /// Returns the version of the section with the given prefix, if any.
    pub fn section_version(&self, prefix: &Prefix<T>) -> Option<u64> {
        self.lookup_section(prefix).map(|(v, _)| v)
    }

    /// Returns the total number of entries in the routing table, excluding our own name.
    // TODO: refactor to include our name?
    pub fn len(&self) -> usize {
        self.all_sections_iter()
            .map(|(_, (_, section))| section.len())
            .sum::<usize>() - 1
    }

    /// Is the table empty? (Returns `true` if no nodes besides our own are known;
    /// empty sections are ignored.)
    pub fn is_empty(&self) -> bool {
        self.our_section.len() == 1 &&
        self.sections
            .values()
            .all(|&(_, ref section)| section.is_empty())
    }

    /// Returns the minimum section size.
    pub fn min_section_size(&self) -> usize {
        self.min_section_size
    }

................................................................................
    /// allow it to be split.
    pub fn min_split_size(&self) -> usize {
        self.min_section_size + SPLIT_BUFFER
    }

    /// Returns whether the table contains the given `name`.
    pub fn has(&self, name: &T) -> bool {
        self.get_section(name)
            .map_or(false, |section| section.contains(name))
    }

    /// Iterates over all nodes known by the routing table, excluding our own name.
    // TODO: do we need to exclude our name?
    pub fn iter(&self) -> Iter<T> {
        let iter = self.all_sections_iter()
            .flat_map(|(_, (_, section))| section.iter());
        Iter {

            inner: Box::new(iter),
            our_name: self.our_name,
        }
    }

    /// Compute an estimate of the size of the network from the size of our routing table.
    ///
    /// Return (estimate, exact), with exact = true iff we have the whole network in our
................................................................................
    /// routing table.
    pub fn network_size_estimate(&self) -> (u64, bool) {
        let known_prefixes = self.prefixes();
        let is_exact = Prefix::default().is_covered_by(known_prefixes.iter());

        // Estimated fraction of the network that we have in our RT.
        // Computed as the sum of 1 / 2^(prefix.bit_count) for all known section prefixes.
        let network_fraction: f64 = known_prefixes
            .iter()
            .map(|p| 1.0 / (p.bit_count() as f64).exp2())
            .sum();

        // Total size estimate = known_nodes / network_fraction
        let network_size = (self.len() + 1) as f64 / network_fraction;

        (network_size.ceil() as u64, is_exact)
................................................................................
    /// `BTreeSet`.
    pub fn other_prefixes(&self) -> BTreeSet<Prefix<T>> {
        self.sections.keys().cloned().collect()
    }

    /// Collects prefixes of all sections known by the routing table into a `BTreeSet`.
    pub fn prefixes(&self) -> BTreeSet<Prefix<T>> {
        self.all_sections_iter()
            .map(|(prefix, _)| prefix)
            .collect()
    }

    /// If our section is the closest one to `name`, returns all names in our section *including
    /// ours*, otherwise returns `None`.
    pub fn close_names(&self, name: &T) -> Option<BTreeSet<T>> {
        if self.our_prefix.matches(name) {
            Some(self.our_section().clone())
................................................................................
    }

    /// Are we among the `count` closest nodes to `name`?
    pub fn is_closest(&self, name: &T, count: usize) -> bool {
        self.closest_names(name, count).is_some()
    }















    /// Returns the `count` closest entries to `name` in the routing table, including our own name,
    /// sorted by ascending distance to `name`. If we are not close, returns `None`.
    pub fn closest_names(&self, name: &T, count: usize) -> Option<Vec<&T>> {
        let result = self.closest_known_names(name, count);
        if result.contains(&&self.our_name) {
            Some(result)
        } else {
................................................................................
        }
    }

    /// Returns the `count-1` closest entries to `name` in the routing table, excluding
    /// our own name, sorted by ascending distance to `name` -  or `None`, if our name
    /// isn't among `count` names closest to `name`.
    pub fn other_closest_names(&self, name: &T, count: usize) -> Option<Vec<&T>> {
        self.closest_names(name, count)
            .map(|mut result| {
                     result.retain(|name| *name != &self.our_name);
                     result
                 })
    }

    /// Returns true if `name` is in our section (including if it is our own name).
    pub fn is_in_our_section(&self, name: &T) -> bool {
        self.our_section.contains(name)
    }

................................................................................
                Ok(())
            }
        } else {
            Err(Error::PeerNameUnsuitable)
        }
    }













    /// Validates a joining node's name.
    pub fn validate_joining_node(&self, name: &T) -> Result<(), Error> {
        if !self.our_prefix.matches(name) {
            return Err(Error::PeerNameUnsuitable);
        }
        if self.our_section.contains(name) {
            return Err(Error::AlreadyExists);
................................................................................
        }
        Ok(())
    }

    /// Adds a contact to the routing table.
    ///
    /// Returns `Err` if `name` already existed in the routing table, or it doesn't fall within any
    /// of our sections, or it's our own name.


    pub fn add(&mut self, name: T) -> Result<(), Error> {
        if name == self.our_name {
            return Err(Error::OwnNameDisallowed);
        }

        if let Some(section) = self.get_section_mut(&name) {
            if !section.insert(name) {
                return Err(Error::AlreadyExists);
            }
        } else {
            return Err(Error::PeerNameUnsuitable);
        }
        Ok(())
    }



    /// Look up a single section (which can be our own).
    fn lookup_section(&self, prefix: &Prefix<T>) -> Option<(u64, &BTreeSet<T>)> {
        if *prefix == self.our_prefix {
            Some((self.our_version, &self.our_section))
        } else {
            self.sections
                .get(prefix)
                .map(|&(ver, ref section)| (ver, section))
        }
    }

    /// Finds the `count` names closest to `name` in the whole routing table.
    fn closest_known_names(&self, name: &T, count: usize) -> Vec<&T> {
        self.all_sections_iter()
            .sorted_by(|&(pfx0, _), &(pfx1, _)| pfx0.cmp_distance(&pfx1, name))
            .into_iter()
            .flat_map(|(_, (_, section))| {
                          section
                              .iter()
                              .sorted_by(|name0, name1| name.cmp_distance(name0, name1))
                      })
            .take(count)
            .collect_vec()
    }

    /// Return true if any neighbouring section needs to merge with our section.
    fn neighbour_needs_merge(&self) -> bool {
        self.neighbour_size_is_below(self.min_section_size)
    }

    /// Return true if any neighbouring section might soon need to merge with our section.
    fn neighbour_might_need_merge(&self) -> bool {
        self.neighbour_size_is_below(self.min_split_size())
    }

    /// Return true if any neighbouring section is below the given size threshold.
    fn neighbour_size_is_below(&self, threshold: usize) -> bool {
        self.sections
            .iter()
            .any(|(prefix, &(_, ref section))| {
                     prefix.popped().is_compatible(&self.our_prefix) && section.len() < threshold
                 })
    }

    /// Returns whether we should split into two sections.
    pub fn should_split(&self) -> bool {
        // If we're currently merging or are close to merging, we shouldn't split.

        if self.neighbour_might_need_merge() {
            return false;
        }

        // Count the number of names which will end up in each new section if our section is split.
        let split_size = self.min_split_size();
        let new_size = self.our_section
            .iter()
            .filter(|name| self.our_name.common_prefix(name) > self.our_prefix.bit_count())
            .count();
        // If either of the two new sections will not contain enough entries, return `false`.
        new_size >= split_size && self.our_section().len() >= split_size + new_size
    }

    /// Splits a section.
    ///
    /// If the section exists in the routing table and has the given version, it is split,
    /// otherwise this function is a no-op. If any of the sections don't satisfy the invariant any
    /// more (i.e. only differ in one bit from our own prefix), they are removed and those contacts
    /// are returned. If the split is happening to our own section, our new prefix is returned in
    /// the optional field.
    pub fn split(&mut self, ver_pfx: VersionedPrefix<T>) -> (Vec<T>, Option<Prefix<T>>) {
        let mut result = vec![];
        let (prefix, version) = ver_pfx.into();
        if prefix == self.our_prefix {
            result = self.split_our_section(version);
            return (result, Some(self.our_prefix));
        }


        let (_version, to_split) = match self.sections.entry(prefix) {
            Entry::Vacant(_) => return (result, None),
            Entry::Occupied(ref entry) if entry.get().0 != version => {
                debug!("{:?} Not splitting section with {:?} ver. {}, \
                       update is for a different version: {}",
                       self.our_name,
                       prefix,
                       entry.get().0,
                       version);
                return (result, None);
            }
            Entry::Occupied(entry) => entry.remove(),
        };
        let prefix0 = prefix.pushed(false);
        let prefix1 = prefix.pushed(true);
        let (section0, section1) = to_split
            .into_iter()
            .partition::<BTreeSet<_>, _>(|name| prefix0.matches(name));

        for (pfx, section) in vec![(prefix0, section0), (prefix1, section1)] {
            if self.our_prefix.is_neighbour(&pfx) {
                self.insert_new_section(pfx, version + 1, section);
            } else {
                result.extend(section);
            }
        }

        (result, None)
    }

    /// Adds the given prefix to the routing table, merging or splitting if necessary. Returns the
    /// entries that have been dropped. If the version is lower or equal to the one in the routing
    /// table, the change is not applied.
    pub fn add_prefix(&mut self, ver_pfx: VersionedPrefix<T>) -> Vec<T> {
        let (prefix, version) = ver_pfx.into();
        // If the prefix isn't relevant to our RT, reject the change.
        if !prefix.is_compatible(&self.our_prefix) && !prefix.is_neighbour(&self.our_prefix) {
            return vec![];


        }



        // If the prefix doesn't supersede an existing one, reject.
        for (pfx, (v, _)) in self.all_sections_iter() {
            if prefix.is_compatible(&pfx) && version <= v {
                trace!("{:?} Not adding {:?} v{} to the RT as the existing {:?} v{} \
                       does not predate it.",
                       self.our_name,





                       prefix,
                       version,
                       pfx,
                       v);
                return vec![];
            }
        }






        let original_sections = mem::replace(&mut self.sections, Sections::new());
        let (sections_to_replace, sections) =
            original_sections
                .into_iter()
                .partition::<BTreeMap<_, _>, _>(|&(ref pfx, _)| prefix.is_compatible(pfx));
        self.sections = sections;
        if prefix.matches(&self.our_name) {
            self.our_prefix = prefix;
            self.our_version = version;
        } else if prefix.is_compatible(&self.our_prefix) {
            self.our_prefix = Prefix::new(prefix.common_prefix(&self.our_name) + 1, self.our_name);
            self.insert_new_section(prefix, version, BTreeSet::new());
        } else {
            self.insert_new_section(prefix, version, BTreeSet::new());
        }





        self.add_missing_prefixes();

        sections_to_replace
            .into_iter()
            .flat_map(|(_, (_, names))| names)
            .chain(mem::replace(&mut self.our_section, iter::once(self.our_name).collect()))
            .filter(|name| {
                        *name != self.our_name && self.add(*name) == Err(Error::PeerNameUnsuitable)
                    })
            .collect()
    }

    /// Removes a contact from the routing table.
    ///
    /// If no entry with that name is found, `Err(Error::NoSuchPeer)` is returned. Otherwise, the
    /// entry is removed from the routing table and `RemovalDetails` is returned. See that struct's
    /// docs for further info.
    pub fn remove(&mut self, name: &T) -> Result<RemovalDetails<T>, Error> {
        let removal_details = RemovalDetails {
            name: *name,
            was_in_our_section: self.our_prefix.matches(name),
        };
        if removal_details.was_in_our_section {
................................................................................
            if self.our_name == *name {
                return Err(Error::OwnNameDisallowed);
            }
            if !self.our_section.remove(name) {
                return Err(Error::NoSuchPeer);
            }
        } else if let Some(prefix) = self.find_section_prefix(name) {
            if let Some(&mut (_, ref mut section)) = self.sections.get_mut(&prefix) {
                if !section.remove(name) {
                    return Err(Error::NoSuchPeer);
                }
            }
        } else {
            return Err(Error::NoSuchPeer);
        }
        Ok(removal_details)
    }

    /// Returns whether we should merge with our sibling section.
    ///
    /// Merging is required if any section has dropped below the minimum size and can only restore
    /// it by ultimately merging with us.
    ///
    /// However, merging happens in simple steps, each of which involves only two sections. If. e.g.
    /// section `1` drops below the minimum size, and the other sections are `01`, `001` and `000`,
    /// then this will return `true` only in the latter two. Once they are merged and have
    /// established all their new connections, it will return `true` in `01` and `00`. Only after
    /// that, the section `0` will merge with section `1`.
    pub fn should_merge(&self) -> bool {



        let bit_count = self.our_prefix.bit_count();






        if bit_count == 0 || !self.sections.contains_key(&self.our_prefix.sibling()) {
            return false; // We can't merge, or we already sent our merge message.
        }










        self.our_section.len() < self.min_section_size || self.neighbour_needs_merge()
    }

    /// When a merge of our own section is triggered (either from our own section or a neighbouring
    /// one) this function handles the incoming merge details from the peers within the merging
    /// sections.
    ///
    /// The actual merge of the section is only done once all expected merging sections have
    /// provided details. See the docs for `OwnMergeState` for full details of the return value.
    pub fn merge_own_section<I>(&mut self,
                                merge_ver_pfx: VersionedPrefix<T>,
                                ver_pfxs: I)
                                -> (OwnMergeState<T>, Vec<T>)
        where I: IntoIterator<Item = VersionedPrefix<T>>
    {
        // TODO: Return an error if they are not compatible instead?
        if !self.our_prefix.is_compatible(merge_ver_pfx.prefix()) ||
           self.our_prefix.bit_count() != merge_ver_pfx.prefix().bit_count() + 1 {
            debug!("{:?} Attempt to call merge_own_section() for an already merged prefix {:?}",
                   self.our_name,

                   merge_ver_pfx);
            return (OwnMergeState::AlreadyMerged, vec![]);
        }





        self.merge(&merge_ver_pfx);
        let dropped_names = ver_pfxs
            .into_iter()
            .flat_map(|ver_pfx| self.add_prefix(ver_pfx))
            .collect();



        self.add_missing_prefixes();
        // The update needs to be sent to all neighbouring sections. However, while those are
        // merging/splitting, our own section might not agree on their prefixes and the message can
        // fail to accumulate. So also include results of flipping one bit in the `merge_prefix`.
        let (merge_pfx, _) = merge_ver_pfx.into();
        let targets = self.sections
            .keys()
            .cloned()
            .chain((0..merge_pfx.bit_count()).map(|i| merge_pfx.with_flipped_bit(i)))
            .collect();
        (OwnMergeState::Completed {
             targets: targets,
             versioned_prefix: self.our_versioned_prefix(),
             section: self.our_section().clone(),
         },
         dropped_names)
    }

    /// Merges all existing compatible sections into the new one defined by `merge_details.prefix`.
    /// Our own section is not included in the merge.
    ///
    /// The appropriate targets (all contacts from `merge_details.sections` which are not currently
    /// held in the routing table) are returned so the caller can establish connections to these
    /// peers and subsequently add them.
    pub fn merge_other_section<I>(&mut self, ver_pfx: VersionedPrefix<T>, members: I) -> BTreeSet<T>
        where I: IntoIterator<Item = T>
    {
        if self.our_prefix.is_compatible(ver_pfx.prefix()) {

            error!("{:?} Attempt to merge other section {:?} when our prefix is {:?}",
                   self.our_name,
                   ver_pfx.prefix(),
                   self.our_prefix);
            return BTreeSet::new();
        }







        self.merge(&ver_pfx);
        // Establish list of provided contacts which are currently missing from our table.
        self.sections
            .get(ver_pfx.prefix())
            .map_or_else(BTreeSet::new, |&(_, ref section)| {
                members
                    .into_iter()
                    .filter(|name| !section.contains(name))
                    .collect()



            })
    }

    /// Returns a collection of nodes to which a message for the given `Authority` should be sent
    /// onwards. In all non-error cases below, the returned collection will have the members of
    /// `exclude` removed, possibly resulting in an empty set being returned.
    ///
    /// * If the destination is an `Authority::Section`:
    ///     - if our section is the closest on the network (i.e. our section's prefix is a prefix of
    ///       the destination), returns all other members of our section; otherwise
    ///     - returns the `route`-th closest member of the RT to the target
    ///
................................................................................
            }
            Authority::PrefixSection(ref prefix) => {
                if prefix.is_compatible(&self.our_prefix) {
                    // only route the message when we have all the targets in our routing table -
                    // this is to prevent spamming the network by sending messages with
                    // intentionally short prefixes
                    if prefix.is_covered_by(self.prefixes().iter()) {
                        let is_compatible = |(pfx, &(_, ref section))| if prefix
                               .is_compatible(pfx) {
                            Some(section)
                        } else {
                            None
                        };
                        return Ok(self.sections
                                      .iter()
                                      .filter_map(is_compatible)
                                      .flat_map(BTreeSet::iter)
                                      .chain(self.our_section
                                                 .iter()
                                                 .filter(|name| **name != self.our_name))
                                      .cloned()
                                      .collect());
                    } else {
                        return Err(Error::CannotRoute);
                    }
                }
                candidates(&prefix.lower_bound())
            }
        };
        Ok(iter::once(self.get_routeth_node(&closest_section, dst.name(), Some(exclude), route)?)
               .collect())
    }

    /// Returns whether we are a part of the given authority.
    pub fn in_authority(&self, auth: &Authority<T>) -> bool {
        match *auth {
            // clients have no routing tables
            Authority::Client { .. } => false,
................................................................................
    /// Returns the section matching the given `name`, if present.
    /// Includes our own name in the case that our prefix matches `name`.
    pub fn get_section(&self, name: &T) -> Option<&BTreeSet<T>> {
        if self.our_prefix.matches(name) {
            return Some(&self.our_section);
        }
        if let Some(prefix) = self.find_section_prefix(name) {
            return self.sections
                       .get(&prefix)
                       .map(|&(_, ref section)| section);
        }
        None
    }

    /// Returns our name.
    pub fn our_name(&self) -> &T {
        &self.our_name
................................................................................

    /// Returns the prefix of the section in which `name` belongs, or `None` if there is no such
    /// section in the routing table.
    pub fn find_section_prefix(&self, name: &T) -> Option<Prefix<T>> {
        if self.our_prefix.matches(name) {
            return Some(self.our_prefix);
        }
        self.sections
            .keys()
            .find(|&prefix| prefix.matches(name))
            .cloned()
    }



    /// Return a minimum length prefix, favouring our prefix if it is one of the shortest.
    pub fn min_len_prefix(&self) -> Prefix<T> {
        *iter::once(&self.our_prefix)
             .chain(self.sections.keys())
             .min_by_key(|prefix| prefix.bit_count())
             .unwrap_or(&self.our_prefix)

    }

    fn split_our_section(&mut self, version: u64) -> Vec<T> {
        if self.our_version != version {
            debug!("{:?} Not splitting our section with {:?} ver. {}, \
                   update is for a different version: {}",
                   self.our_name,
                   self.our_prefix,
                   self.our_version,
                   version);
            return Vec::new(); // Wrong version.
        }
        let next_bit = self.our_name.bit(self.our_prefix.bit_count());
        let other_prefix = self.our_prefix.pushed(!next_bit);
        self.our_prefix = self.our_prefix.pushed(next_bit);
        let (our_new_section, other_section) =
            self.our_section
                .iter()
                .partition::<BTreeSet<_>, _>(|name| self.our_prefix.matches(name));
        self.our_section = our_new_section;
        self.our_version = version + 1;
        // Drop sections that ceased to be our neighbours.
        let sections_to_remove = self.sections
            .keys()
            .filter(|prefix| !prefix.is_neighbour(&self.our_prefix))
            .cloned()
            .collect_vec();
        self.insert_new_section(other_prefix, version + 1, other_section);
        sections_to_remove
            .into_iter()
            .filter_map(|prefix| {
                            self.sections
                                .remove(&prefix)
                                .map(|(_, section)| section)
                        })
            .flat_map(BTreeSet::into_iter)
            .collect()
    }

    /// Inserts the given section. Logs an error if it already exists.
    fn insert_new_section(&mut self, prefix: Prefix<T>, version: u64, section: BTreeSet<T>) {
        match self.sections.entry(prefix) {
            Entry::Vacant(entry) => {
                let _section_ref = entry.insert((version, section));
            }
            Entry::Occupied(entry) => {
                error!("{:?} Inserting section {:?}, but already has members {:?}. This is a bug!",
                       self.our_name,
                       prefix,
                       entry.get());
                let &mut (ref mut v, ref mut s) = entry.into_mut();
                if *v > version {
                    return; // Wrong version.
                }
                *v = version;
                s.extend(section);
            }
        }
    }






    fn merge(&mut self, new_ver_pfx: &VersionedPrefix<T>) {
        if new_ver_pfx.prefix().is_extension_of(&self.our_prefix) ||
           self.sections
               .keys()

               .any(|pfx| new_ver_pfx.prefix().is_extension_of(pfx)) {
            return; // Not a merge!







        }












        let dropped_names = self.add_prefix(*new_ver_pfx);
        if !dropped_names.is_empty() {
            error!("{:?} Dropped names when merging {:?}: {:?}",
                   self.our_name,


                   new_ver_pfx,
                   dropped_names);
        }
    }

    /// Inserts empty sections so that the prefixes cover all neighbouring areas of the namespace.
    fn add_missing_prefixes(&mut self) {
        let mut prefix = self.our_prefix;
        let mut missing_pfxs = vec![];


        while prefix.bit_count() > 0 {
            missing_pfxs.push(prefix.sibling());
            prefix = prefix.popped();
        }
        while let Some(pfx) = missing_pfxs.pop() {
            if !pfx.is_covered_by(self.sections.keys()) && pfx.is_neighbour(&self.our_prefix) {
                if self.sections.keys().any(|p| pfx.is_compatible(p)) {
                    missing_pfxs.push(pfx.pushed(true));
                    missing_pfxs.push(pfx.pushed(false));
                } else {
                    self.insert_new_section(pfx, 0, BTreeSet::new());
                }
            }
        }
    }

    /// Get a mutable reference to whichever section matches the given name. If our own section,
    /// our name is included.
    fn get_section_mut(&mut self, name: &T) -> Option<&mut BTreeSet<T>> {
        if self.our_prefix.matches(name) {
            return Some(&mut self.our_section);
        }
        if let Some(prefix) = self.find_section_prefix(name) {
            return self.sections
                       .get_mut(&prefix)
                       .map(|&mut (_, ref mut section)| section);
        }
        None
    }

    /// Returns the prefix of the closest non-empty section to `name`, regardless of whether `name`
    /// belongs in that section or not, and the section itself.
    fn closest_section(&self, name: &T) -> (&Prefix<T>, &BTreeSet<T>) {
        let mut result = (&self.our_prefix, &self.our_section);
        for (prefix, &(_, ref section)) in &self.sections {
            if !section.is_empty() && result.0.cmp_distance(prefix, name) == Ordering::Greater {
                result = (prefix, section)
            }
        }
        result
    }

    /// Gets the `route`-th name from a collection of names
    fn get_routeth_name<'a, U: IntoIterator<Item = &'a T>>(names: U,
                                                           dst_name: &T,
                                                           route: usize)
                                                           -> &'a T {
        let sorted_names = names
            .into_iter()
            .sorted_by(|&lhs, &rhs| dst_name.cmp_distance(lhs, rhs));
        sorted_names[route % sorted_names.len()]
    }

    /// Returns the `route`-th node in the given section, sorted by distance to `target`
    fn get_routeth_node(&self,
                        section: &BTreeSet<T>,
................................................................................
                return warn(format!("Name {} doesn't match section prefix {:?}: {:?}",
                                    name.debug_binary(),
                                    self.our_prefix,
                                    self));
            }
        }

        for (prefix, &(_, ref section)) in &self.sections {
            if has_enough_nodes && section.len() < self.min_section_size {
                if section.len() <= 1 && allow_small_sections {
                    continue;
                }
                return warn(format!("Minimum group size not met for group {:?}: {:?}",
                                    prefix,
                                    self));
................................................................................
                                        name.debug_binary(),
                                        prefix,
                                        self));
                }
            }
        }

        let all_are_neighbours = self.sections
            .keys()
            .all(|&x| self.our_prefix.is_neighbour(&x));
        let all_neighbours_covered = {
            let prefixes = self.prefixes();
            (0..self.our_prefix.bit_count()).all(|i| {
                                                     self.our_prefix
                                                         .with_flipped_bit(i)
                                                         .is_covered_by(&prefixes)
                                                 })
        };
        if !all_are_neighbours {
            return warn(format!("Some sections in the RT aren't neighbours of our section: {:?}",
                                self));
        }
        if !all_neighbours_covered {
            return warn(format!("Some neighbours aren't fully covered by the RT: {:?}", self));
................................................................................
        writeln!(formatter, "RoutingTable {{")?;
        writeln!(formatter, "\tmin_section_size: {},", self.min_section_size)?;
        writeln!(formatter,
                 "\tour_name: {:?} ({}),",
                 self.our_name,
                 self.our_name.debug_binary())?;
        writeln!(formatter, "\tour_prefix: {:?}", self.our_prefix)?;
        writeln!(formatter, "\tour_version: {}", self.our_version)?;



        let sections = self.all_sections_iter().collect::<BTreeSet<_>>();
        for (section_index, &(prefix, (version, section))) in sections.iter().enumerate() {
            write!(formatter,
                   "\tsection {} with {:?} v{}: {{\n",
                   section_index,
                   prefix,
                   version)?;
            for (name_index, name) in section.iter().enumerate() {
                let comma = if name_index == section.len() - 1 {
                    ""
                } else {
                    ","
                };
                writeln!(formatter,
................................................................................
        Binary::fmt(self, formatter)
    }
}


#[cfg(test)]
mod tests {


    use super::*;
    use super::SPLIT_BUFFER;
    use itertools::Itertools;
    use std::collections::BTreeSet;
    use std::str::FromStr;

    #[test]
    fn small() {
        let name = 123u32;
        let table = RoutingTable::new(name, 6);
        assert_eq!(*table.our_name(), name);
        assert_eq!(table.len(), 0);
        assert!(table.is_empty());
        assert_eq!(table.iter().count(), 0);
        assert_eq!(table.all_sections_iter().count(), 1);
    }

    // Adds `min_split_size() - 1` entries to `table`, starting at `name` and incrementing it by 1
    // each time.
    fn add_sequential_entries(table: &mut RoutingTable<u16>, name: &mut u16) {
        for _ in 1..table.min_split_size() {
            assert_eq!(table.add(*name), Ok(()));
            assert!(!table.should_split());
            table.verify_invariant();
            *name += 1;
        }
    }

    // Test explicitly covers `close_names()`, `other_close_names()`, `is_in_our_section()` and
    // `need_to_add()` while also implicitly testing `add()` and `split()`.
................................................................................
        let mut section_00_name = our_name + 1;
        let mut section_10_name = our_name.with_flipped_bit(0);
        add_sequential_entries(&mut table, &mut section_00_name);
        add_sequential_entries(&mut table, &mut section_10_name);
        expected_rt_len += 2 * (table.min_split_size() - 1);

        // Add one name to the other half to trigger the split to sections 0 and 1.
        assert_eq!(table.add(section_10_name), Ok(()));
        assert!(table.should_split());
        expected_rt_len += 1;
        let mut expected_own_prefix = Prefix::new(0, our_name);
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        let (nodes_to_drop, our_new_prefix) = table.split(expected_own_prefix.with_version(0));
        expected_own_prefix = Prefix::new(1, our_name);
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        assert_eq!(unwrap!(our_new_prefix), expected_own_prefix);
        assert!(nodes_to_drop.is_empty());
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);
        assert_eq!(table.all_sections().len(), 2);
................................................................................
        let mut section_01_name = our_name.with_flipped_bit(1);
        let mut section_11_name = section_10_name.with_flipped_bit(1);
        add_sequential_entries(&mut table, &mut section_01_name);
        add_sequential_entries(&mut table, &mut section_11_name);
        expected_rt_len += 2 * (table.min_split_size() - 1);

        // Trigger split in our own section first to yield sections 00, 01 and 1.
        assert_eq!(table.add(section_01_name), Ok(()));
        assert!(table.should_split());
        expected_rt_len += 1;
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        let (nodes_to_drop, our_new_prefix) = table.split(expected_own_prefix.with_version(1));
        expected_own_prefix = Prefix::new(2, our_name);
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        assert_eq!(unwrap!(our_new_prefix), expected_own_prefix);
        assert!(nodes_to_drop.is_empty());
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);
        assert_eq!(table.all_sections().len(), 3);
        assert_eq!(table.our_section().len(), table.min_split_size());

        // Now trigger split in section 1, which should cause section 11 to get ejected, leaving
        // sections 00, 01 and 10.
        assert_eq!(table.add(section_11_name), Ok(()));
        assert!(!table.should_split());
        expected_rt_len += 1;
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        let (nodes_to_drop, our_new_prefix) =
            table.split(Prefix::new(1, section_11_name).with_version(1));
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        assert!(our_new_prefix.is_none());
        assert_eq!(nodes_to_drop.len(), table.min_split_size());
        let mut drop_prefix = Prefix::new(2, section_11_name);
        assert!(nodes_to_drop
                    .iter()
                    .all(|name| drop_prefix.matches(name)));
        expected_rt_len -= nodes_to_drop.len();
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);
        assert_eq!(table.all_sections().len(), 3);
        assert_eq!(table.our_section().len(), table.min_split_size());

        // Add `min_split_size - 1` with names 001... and names 011... to get sections 00 and 01
................................................................................
        let mut section_011_name = section_001_name.with_flipped_bit(1);
        add_sequential_entries(&mut table, &mut section_001_name);
        add_sequential_entries(&mut table, &mut section_011_name);
        expected_rt_len += 2 * (table.min_split_size() - 1);

        // Trigger split in other section (i.e. section 01) first this time to yield sections 00,
        // 010, 011 and 10.
        assert_eq!(table.add(section_011_name), Ok(()));
        assert!(!table.should_split());
        expected_rt_len += 1;
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        let (nodes_to_drop, our_new_prefix) =
            table.split(Prefix::new(2, section_011_name).with_version(2));
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        assert!(our_new_prefix.is_none());
        assert!(nodes_to_drop.is_empty());
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);
        assert_eq!(table.all_sections().len(), 4);
        assert_eq!(table.our_section().len(), 2 * table.min_split_size() - 1);

        // Now trigger split in own section (i.e. section 00), which should cause section 011 to get
        // ejected, leaving sections 000, 001, 010 and 10.
        assert_eq!(table.add(section_001_name), Ok(()));
        assert!(table.should_split());
        expected_rt_len += 1;
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        let (nodes_to_drop, our_new_prefix) =
            table.split(expected_own_prefix.with_version(expected_own_prefix.bit_count() as u64));
        expected_own_prefix = Prefix::new(3, our_name);
        assert_eq!(*table.our_prefix(), expected_own_prefix);
        assert_eq!(unwrap!(our_new_prefix), expected_own_prefix);
        assert_eq!(nodes_to_drop.len(), table.min_split_size());
        drop_prefix = Prefix::new(3, section_011_name);
        assert!(nodes_to_drop
                    .iter()
                    .all(|name| drop_prefix.matches(name)));
        expected_rt_len -= nodes_to_drop.len();
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);
        assert_eq!(table.all_sections().len(), 4);
        assert_eq!(table.our_section().len(), table.min_split_size());

        // Try to add a name which is already in the RT.
        assert_eq!(table.add(section_001_name), Err(Error::AlreadyExists));

        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);

        // Try to add our own name.
        assert_eq!(table.add(our_name), Err(Error::OwnNameDisallowed));
        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);

        // Try to add a name which doesn't fit any section.
        assert_eq!(table.add(nodes_to_drop[0]), Err(Error::PeerNameUnsuitable));

        table.verify_invariant();
        assert_eq!(table.len(), expected_rt_len);

        // Check `is_in_our_section()`.
        assert!(table.is_in_our_section(&our_name));
        assert!(table.is_in_our_section(&(section_00_name - 1)));
        assert!(!table.is_in_our_section(&section_001_name));
................................................................................
        assert!(our_section.contains(&our_name));
        assert_eq!(unwrap!(table.close_names(&our_name)), our_section);
        assert_eq!(unwrap!(table.close_names(&section_00_name)), our_section);
        assert!(table.close_names(&section_001_name).is_none());
        assert!(table.close_names(&section_10_name).is_none());

        // Check `other_close_names()`.
        let our_section_without_us = our_section
            .into_iter()
            .filter(|name| *name != our_name)
            .collect::<BTreeSet<_>>();
        assert_eq!(unwrap!(table.other_close_names(&our_name)),
                   our_section_without_us);
        assert_eq!(unwrap!(table.other_close_names(&section_00_name)),
                   our_section_without_us);
        assert!(table.other_close_names(&section_001_name).is_none());
        assert!(table.other_close_names(&section_10_name).is_none());

................................................................................
    }

    #[test]
    fn test_closest_names() {
        let our_name = 0u16;
        let mut table = RoutingTable::new(our_name, 8);
        // initialize the table
        unwrap!(table.add(0x8000));
        unwrap!(table.add(0x4000));
        unwrap!(table.add(0x2000));
        unwrap!(table.add(0x1000));
        unwrap!(table.add(0x0800));
        unwrap!(table.add(0x0400));
        unwrap!(table.add(0x0200));
        unwrap!(table.add(0x0100));
        unwrap!(table.add(0x0080));
        unwrap!(table.add(0x0040));

        let mut name = 0xFFFF;
        assert!(table.closest_names(&name, 10).is_none());
        assert!(table.other_closest_names(&name, 10).is_none());
        assert!(table.closest_names(&name, 11).is_some());
        let result = unwrap!(table.other_closest_names(&name, 11));
        assert_eq!(result.len(), 10);
................................................................................

    #[test]
    fn test_add_prefix() {
        let our_name = 0u8;
        let mut table = RoutingTable::new(our_name, 1);
        // Add 10, 20, 30, 40, 50, 60, 70, 80, 90, A0, B0, C0, D0, E0 and F0.
        for i in 1..0x10 {
            unwrap!(table.add(i * 0x10));
        }
        assert_eq!(prefixes_from_strs(vec![""]), table.prefixes());
        assert_eq!(Vec::<u8>::new(),
                   table.add_prefix(unwrap!(Prefix::from_str("01")).with_version(2)));
        assert_eq!(prefixes_from_strs(vec!["1", "00", "01"]), table.prefixes());
        assert_eq!(Vec::<u8>::new(),
                   table
                       .add_prefix(unwrap!(Prefix::from_str("111")).with_version(4))
                       .into_iter()
                       .sorted());
        assert_eq!(prefixes_from_strs(vec!["1", "00", "01"]), table.prefixes());
        assert_eq!(vec![0xc0, 0xd0, 0xe0, 0xf0u8],

                   table
                       .add_prefix(unwrap!(Prefix::from_str("101")).with_version(4))
                       .into_iter()
                       .sorted());
        assert_eq!(prefixes_from_strs(vec!["101", "100", "01", "00"]),
                   table.prefixes());
        assert_eq!(Vec::<u8>::new(),
                   table.add_prefix(unwrap!(Prefix::from_str("0")).with_version(7)));
        assert_eq!(prefixes_from_strs(vec!["101", "11", "100", "0"]),
                   table.prefixes());
        assert_eq!(Vec::<u8>::new(),
                   table.add_prefix(unwrap!(Prefix::from_str("")).with_version(15)));
        assert_eq!(prefixes_from_strs(vec![""]), table.prefixes());
    }

    #[test]
    fn test_add_prefix_outdated_version() {
        let our_name = 0u8;
        let mut table = RoutingTable::<u8>::new(our_name, 1);
        // Add 10, 20, 30, 40, 50, 60, 70, 80, 90, A0, B0, C0, D0, E0 and F0.
        for i in 1..0x10 {
            unwrap!(table.add(i * 0x10));
        }
        let empty = Vec::<u8>::new();

        // Split into {0, 1}
        assert_eq!(empty, table.add_prefix(prefix_str("0").with_version(1)));
        assert_eq!(Some(1), table.section_version(&prefix_str("0")));
        assert_eq!(Some(0), table.section_version(&prefix_str("1")));

        // Split 0 into {00, 01}.
        assert_eq!(empty, table.add_prefix(prefix_str("00").with_version(2)));
        assert_eq!(Some(2), table.section_version(&prefix_str("00")));
        assert_eq!(Some(0), table.section_version(&prefix_str("01")));
        assert_eq!(Some(0), table.section_version(&prefix_str("1")));

        // Split into 1 into {10,11}, dropping the nodes in 11.
        assert_eq!(vec![0xc0, 0xd0, 0xe0, 0xf0u8],
                   table
                       .add_prefix(prefix_str("10").with_version(2))
                       .into_iter()
                       .sorted());
        assert_eq!(prefixes_from_strs(vec!["10", "01", "00"]), table.prefixes());

        // Simulate a missed update for the split from 10 to 100 and 101 and subsequent merge.
        assert_eq!(empty, table.add_prefix(prefix_str("10").with_version(4)));
        assert_eq!(Some(4), table.section_version(&prefix_str("10")));

        // RT shouldn't change if it now gets an update for prefix 100 v3.
        assert_eq!(empty, table.add_prefix(prefix_str("100").with_version(3)));
        assert_eq!(Some(4), table.section_version(&prefix_str("10")));
        assert_eq!(prefixes_from_strs(vec!["10", "01", "00"]), table.prefixes());

        // Similarly, none of these bogus updates should be accepted.
        assert_eq!(empty, table.add_prefix(prefix_str("").with_version(0)));
        assert_eq!(empty, table.add_prefix(prefix_str("0").with_version(1)));
        assert_eq!(empty, table.add_prefix(prefix_str("101").with_version(3)));
        assert_eq!(prefixes_from_strs(vec!["10", "01", "00"]), table.prefixes());

        // Finally, adding an existing prefix (01) should update its version.
        assert_eq!(empty, table.add_prefix(prefix_str("01").with_version(2)));
        assert_eq!(Some(2), table.section_version(&prefix_str("01")));
    }

    fn prefix_str(s: &str) -> Prefix<u8> {
        unwrap!(Prefix::from_str(s))
    }

    fn prefixes_from_strs(strs: Vec<&str>) -> BTreeSet<Prefix<u8>> {
        strs.into_iter()
            .map(|s| unwrap!(Prefix::from_str(s)))
            .collect()
    }
}