protocol-quic 0.0.0

data/ext/ngtcp2/lib/ngtcp2_pq.c

@@ -0,0 +1,164 @@
+/*
+ * ngtcp2
+ *
+ * Copyright (c) 2017 ngtcp2 contributors
+ * Copyright (c) 2012 nghttp2 contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+#include "ngtcp2_pq.h"
+
+#include <assert.h>
+
+#include "ngtcp2_macro.h"
+
+void ngtcp2_pq_init(ngtcp2_pq *pq, ngtcp2_less less, const ngtcp2_mem *mem) {
+  pq->mem = mem;
+  pq->capacity = 0;
+  pq->q = NULL;
+  pq->length = 0;
+  pq->less = less;
+}
+
+void ngtcp2_pq_free(ngtcp2_pq *pq) {
+  ngtcp2_mem_free(pq->mem, pq->q);
+  pq->q = NULL;
+}
+
+static void swap(ngtcp2_pq *pq, size_t i, size_t j) {
+  ngtcp2_pq_entry *a = pq->q[i];
+  ngtcp2_pq_entry *b = pq->q[j];
+
+  pq->q[i] = b;
+  b->index = i;
+  pq->q[j] = a;
+  a->index = j;
+}
+
+static void bubble_up(ngtcp2_pq *pq, size_t index) {
+  size_t parent;
+  while (index != 0) {
+    parent = (index - 1) / 2;
+    if (!pq->less(pq->q[index], pq->q[parent])) {
+      return;
+    }
+    swap(pq, parent, index);
+    index = parent;
+  }
+}
+
+int ngtcp2_pq_push(ngtcp2_pq *pq, ngtcp2_pq_entry *item) {
+  if (pq->capacity <= pq->length) {
+    void *nq;
+    size_t ncapacity;
+
+    ncapacity = ngtcp2_max(4, (pq->capacity * 2));
+
+    nq = ngtcp2_mem_realloc(pq->mem, pq->q,
+                            ncapacity * sizeof(ngtcp2_pq_entry *));
+    if (nq == NULL) {
+      return NGTCP2_ERR_NOMEM;
+    }
+    pq->capacity = ncapacity;
+    pq->q = nq;
+  }
+  pq->q[pq->length] = item;
+  item->index = pq->length;
+  ++pq->length;
+  bubble_up(pq, pq->length - 1);
+  return 0;
+}
+
+ngtcp2_pq_entry *ngtcp2_pq_top(ngtcp2_pq *pq) {
+  assert(pq->length);
+  return pq->q[0];
+}
+
+static void bubble_down(ngtcp2_pq *pq, size_t index) {
+  size_t i, j, minindex;
+  for (;;) {
+    j = index * 2 + 1;
+    minindex = index;
+    for (i = 0; i < 2; ++i, ++j) {
+      if (j >= pq->length) {
+        break;
+      }
+      if (pq->less(pq->q[j], pq->q[minindex])) {
+        minindex = j;
+      }
+    }
+    if (minindex == index) {
+      return;
+    }
+    swap(pq, index, minindex);
+    index = minindex;
+  }
+}
+
+void ngtcp2_pq_pop(ngtcp2_pq *pq) {
+  if (pq->length > 0) {
+    pq->q[0] = pq->q[pq->length - 1];
+    pq->q[0]->index = 0;
+    --pq->length;
+    bubble_down(pq, 0);
+  }
+}
+
+void ngtcp2_pq_remove(ngtcp2_pq *pq, ngtcp2_pq_entry *item) {
+  assert(pq->q[item->index] == item);
+
+  if (item->index == 0) {
+    ngtcp2_pq_pop(pq);
+    return;
+  }
+
+  if (item->index == pq->length - 1) {
+    --pq->length;
+    return;
+  }
+
+  pq->q[item->index] = pq->q[pq->length - 1];
+  pq->q[item->index]->index = item->index;
+  --pq->length;
+
+  if (pq->less(item, pq->q[item->index])) {
+    bubble_down(pq, item->index);
+  } else {
+    bubble_up(pq, item->index);
+  }
+}
+
+int ngtcp2_pq_empty(ngtcp2_pq *pq) { return pq->length == 0; }
+
+size_t ngtcp2_pq_size(ngtcp2_pq *pq) { return pq->length; }
+
+int ngtcp2_pq_each(ngtcp2_pq *pq, ngtcp2_pq_item_cb fun, void *arg) {
+  size_t i;
+
+  if (pq->length == 0) {
+    return 0;
+  }
+  for (i = 0; i < pq->length; ++i) {
+    if ((*fun)(pq->q[i], arg)) {
+      return 1;
+    }
+  }
+  return 0;
+}

data/ext/ngtcp2/lib/ngtcp2_pq.h

@@ -0,0 +1,126 @@
+/*
+ * ngtcp2
+ *
+ * Copyright (c) 2017 ngtcp2 contributors
+ * Copyright (c) 2012 nghttp2 contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+#ifndef NGTCP2_PQ_H
+#define NGTCP2_PQ_H
+
+#ifdef HAVE_CONFIG_H
+#  include <config.h>
+#endif /* HAVE_CONFIG_H */
+
+#include <ngtcp2/ngtcp2.h>
+
+#include "ngtcp2_mem.h"
+
+/* Implementation of priority queue */
+
+/* NGTCP2_PQ_BAD_INDEX is the priority queue index which indicates
+   that an entry is not queued.  Assigning this value to
+   ngtcp2_pq_entry.index can check that the entry is queued or not. */
+#define NGTCP2_PQ_BAD_INDEX SIZE_MAX
+
+typedef struct ngtcp2_pq_entry {
+  size_t index;
+} ngtcp2_pq_entry;
+
+/* "less" function, return nonzero if |lhs| is less than |rhs|. */
+typedef int (*ngtcp2_less)(const ngtcp2_pq_entry *lhs,
+                           const ngtcp2_pq_entry *rhs);
+
+typedef struct ngtcp2_pq {
+  /* The pointer to the pointer to the item stored */
+  ngtcp2_pq_entry **q;
+  /* Memory allocator */
+  const ngtcp2_mem *mem;
+  /* The number of items stored */
+  size_t length;
+  /* The maximum number of items this pq can store. This is
+     automatically extended when length is reached to this value. */
+  size_t capacity;
+  /* The less function between items */
+  ngtcp2_less less;
+} ngtcp2_pq;
+
+/*
+ * Initializes priority queue |pq| with compare function |cmp|.
+ */
+void ngtcp2_pq_init(ngtcp2_pq *pq, ngtcp2_less less, const ngtcp2_mem *mem);
+
+/*
+ * Deallocates any resources allocated for |pq|.  The stored items are
+ * not freed by this function.
+ */
+void ngtcp2_pq_free(ngtcp2_pq *pq);
+
+/*
+ * Adds |item| to the priority queue |pq|.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * NGTCP2_ERR_NOMEM
+ *     Out of memory.
+ */
+int ngtcp2_pq_push(ngtcp2_pq *pq, ngtcp2_pq_entry *item);
+
+/*
+ * Returns item at the top of the queue |pq|.  It is undefined if the
+ * queue is empty.
+ */
+ngtcp2_pq_entry *ngtcp2_pq_top(ngtcp2_pq *pq);
+
+/*
+ * Pops item at the top of the queue |pq|. The popped item is not
+ * freed by this function.
+ */
+void ngtcp2_pq_pop(ngtcp2_pq *pq);
+
+/*
+ * Returns nonzero if the queue |pq| is empty.
+ */
+int ngtcp2_pq_empty(ngtcp2_pq *pq);
+
+/*
+ * Returns the number of items in the queue |pq|.
+ */
+size_t ngtcp2_pq_size(ngtcp2_pq *pq);
+
+typedef int (*ngtcp2_pq_item_cb)(ngtcp2_pq_entry *item, void *arg);
+
+/*
+ * Applys |fun| to each item in |pq|.  The |arg| is passed as arg
+ * parameter to callback function.  This function must not change the
+ * ordering key.  If the return value from callback is nonzero, this
+ * function returns 1 immediately without iterating remaining items.
+ * Otherwise this function returns 0.
+ */
+int ngtcp2_pq_each(ngtcp2_pq *pq, ngtcp2_pq_item_cb fun, void *arg);
+
+/*
+ * Removes |item| from priority queue.
+ */
+void ngtcp2_pq_remove(ngtcp2_pq *pq, ngtcp2_pq_entry *item);
+
+#endif /* NGTCP2_PQ_H */

data/ext/ngtcp2/lib/ngtcp2_pv.c

@@ -0,0 +1,172 @@
+/*
+ * ngtcp2
+ *
+ * Copyright (c) 2019 ngtcp2 contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+#include "ngtcp2_pv.h"
+
+#include <string.h>
+#include <assert.h>
+
+#include "ngtcp2_mem.h"
+#include "ngtcp2_log.h"
+#include "ngtcp2_macro.h"
+#include "ngtcp2_addr.h"
+
+void ngtcp2_pv_entry_init(ngtcp2_pv_entry *pvent, const uint8_t *data,
+                          ngtcp2_tstamp expiry, uint8_t flags) {
+  memcpy(pvent->data, data, sizeof(pvent->data));
+  pvent->expiry = expiry;
+  pvent->flags = flags;
+}
+
+int ngtcp2_pv_new(ngtcp2_pv **ppv, const ngtcp2_dcid *dcid,
+                  ngtcp2_duration timeout, uint8_t flags, ngtcp2_log *log,
+                  const ngtcp2_mem *mem) {
+  (*ppv) = ngtcp2_mem_malloc(mem, sizeof(ngtcp2_pv));
+  if (*ppv == NULL) {
+    return NGTCP2_ERR_NOMEM;
+  }
+
+  ngtcp2_static_ringbuf_pv_ents_init(&(*ppv)->ents);
+
+  ngtcp2_dcid_copy(&(*ppv)->dcid, dcid);
+
+  (*ppv)->mem = mem;
+  (*ppv)->log = log;
+  (*ppv)->timeout = timeout;
+  (*ppv)->fallback_pto = 0;
+  (*ppv)->started_ts = UINT64_MAX;
+  (*ppv)->probe_pkt_left = NGTCP2_PV_NUM_PROBE_PKT;
+  (*ppv)->round = 0;
+  (*ppv)->flags = flags;
+
+  return 0;
+}
+
+void ngtcp2_pv_del(ngtcp2_pv *pv) {
+  if (pv == NULL) {
+    return;
+  }
+  ngtcp2_mem_free(pv->mem, pv);
+}
+
+void ngtcp2_pv_add_entry(ngtcp2_pv *pv, const uint8_t *data,
+                         ngtcp2_tstamp expiry, uint8_t flags,
+                         ngtcp2_tstamp ts) {
+  ngtcp2_pv_entry *ent;
+
+  assert(pv->probe_pkt_left);
+
+  if (ngtcp2_ringbuf_len(&pv->ents.rb) == 0) {
+    pv->started_ts = ts;
+  }
+
+  ent = ngtcp2_ringbuf_push_back(&pv->ents.rb);
+  ngtcp2_pv_entry_init(ent, data, expiry, flags);
+
+  pv->flags &= (uint8_t)~NGTCP2_PV_FLAG_CANCEL_TIMER;
+  --pv->probe_pkt_left;
+}
+
+int ngtcp2_pv_validate(ngtcp2_pv *pv, uint8_t *pflags, const uint8_t *data) {
+  size_t len = ngtcp2_ringbuf_len(&pv->ents.rb);
+  size_t i;
+  ngtcp2_pv_entry *ent;
+
+  if (len == 0) {
+    return NGTCP2_ERR_INVALID_STATE;
+  }
+
+  for (i = 0; i < len; ++i) {
+    ent = ngtcp2_ringbuf_get(&pv->ents.rb, i);
+    if (memcmp(ent->data, data, sizeof(ent->data)) == 0) {
+      *pflags = ent->flags;
+      ngtcp2_log_info(pv->log, NGTCP2_LOG_EVENT_PTV, "path has been validated");
+      return 0;
+    }
+  }
+
+  return NGTCP2_ERR_INVALID_ARGUMENT;
+}
+
+void ngtcp2_pv_handle_entry_expiry(ngtcp2_pv *pv, ngtcp2_tstamp ts) {
+  ngtcp2_pv_entry *ent;
+
+  if (ngtcp2_ringbuf_len(&pv->ents.rb) == 0) {
+    return;
+  }
+
+  ent = ngtcp2_ringbuf_get(&pv->ents.rb, ngtcp2_ringbuf_len(&pv->ents.rb) - 1);
+
+  if (ent->expiry > ts) {
+    return;
+  }
+
+  ++pv->round;
+  pv->probe_pkt_left = NGTCP2_PV_NUM_PROBE_PKT;
+}
+
+int ngtcp2_pv_should_send_probe(ngtcp2_pv *pv) {
+  return pv->probe_pkt_left > 0;
+}
+
+int ngtcp2_pv_validation_timed_out(ngtcp2_pv *pv, ngtcp2_tstamp ts) {
+  ngtcp2_tstamp t;
+  ngtcp2_pv_entry *ent;
+
+  if (pv->started_ts == UINT64_MAX) {
+    return 0;
+  }
+
+  assert(ngtcp2_ringbuf_len(&pv->ents.rb));
+
+  ent = ngtcp2_ringbuf_get(&pv->ents.rb, ngtcp2_ringbuf_len(&pv->ents.rb) - 1);
+
+  t = pv->started_ts + pv->timeout;
+  t = ngtcp2_max(t, ent->expiry);
+
+  return t <= ts;
+}
+
+ngtcp2_tstamp ngtcp2_pv_next_expiry(ngtcp2_pv *pv) {
+  ngtcp2_pv_entry *ent;
+
+  if ((pv->flags & NGTCP2_PV_FLAG_CANCEL_TIMER) ||
+      ngtcp2_ringbuf_len(&pv->ents.rb) == 0) {
+    return UINT64_MAX;
+  }
+
+  ent = ngtcp2_ringbuf_get(&pv->ents.rb, ngtcp2_ringbuf_len(&pv->ents.rb) - 1);
+
+  return ent->expiry;
+}
+
+void ngtcp2_pv_cancel_expired_timer(ngtcp2_pv *pv, ngtcp2_tstamp ts) {
+  ngtcp2_tstamp expiry = ngtcp2_pv_next_expiry(pv);
+
+  if (expiry > ts) {
+    return;
+  }
+
+  pv->flags |= NGTCP2_PV_FLAG_CANCEL_TIMER;
+}

data/ext/ngtcp2/lib/ngtcp2_pv.h

@@ -0,0 +1,194 @@
+/*
+ * ngtcp2
+ *
+ * Copyright (c) 2019 ngtcp2 contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining
+ * a copy of this software and associated documentation files (the
+ * "Software"), to deal in the Software without restriction, including
+ * without limitation the rights to use, copy, modify, merge, publish,
+ * distribute, sublicense, and/or sell copies of the Software, and to
+ * permit persons to whom the Software is furnished to do so, subject to
+ * the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be
+ * included in all copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+ * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+ * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ * LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ * OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+ */
+#ifndef NGTCP2_PV_H
+#define NGTCP2_PV_H
+
+#ifdef HAVE_CONFIG_H
+#  include <config.h>
+#endif /* HAVE_CONFIG_H */
+
+#include <ngtcp2/ngtcp2.h>
+
+#include "ngtcp2_cid.h"
+#include "ngtcp2_ringbuf.h"
+
+/* NGTCP2_PV_MAX_ENTRIES is the maximum number of entries that
+   ngtcp2_pv can contain.  It must be power of 2. */
+#define NGTCP2_PV_MAX_ENTRIES 8
+/* NGTCP2_PV_NUM_PROBE_PKT is the number of probe packets containing
+   PATH_CHALLENGE sent at a time. */
+#define NGTCP2_PV_NUM_PROBE_PKT 2
+
+typedef struct ngtcp2_log ngtcp2_log;
+
+typedef struct ngtcp2_frame_chain ngtcp2_frame_chain;
+
+/* NGTCP2_PV_ENTRY_FLAG_NONE indicates that no flag is set. */
+#define NGTCP2_PV_ENTRY_FLAG_NONE 0x00u
+/* NGTCP2_PV_ENTRY_FLAG_UNDERSIZED indicates that UDP datagram which
+   contains PATH_CHALLENGE is undersized (< 1200 bytes) */
+#define NGTCP2_PV_ENTRY_FLAG_UNDERSIZED 0x01u
+
+typedef struct ngtcp2_pv_entry {
+  /* expiry is the timestamp when this PATH_CHALLENGE expires. */
+  ngtcp2_tstamp expiry;
+  /* flags is zero or more of NGTCP2_PV_ENTRY_FLAG_*. */
+  uint8_t flags;
+  /* data is a byte string included in PATH_CHALLENGE. */
+  uint8_t data[8];
+} ngtcp2_pv_entry;
+
+void ngtcp2_pv_entry_init(ngtcp2_pv_entry *pvent, const uint8_t *data,
+                          ngtcp2_tstamp expiry, uint8_t flags);
+
+/* NGTCP2_PV_FLAG_NONE indicates no flag is set. */
+#define NGTCP2_PV_FLAG_NONE 0x00u
+/* NGTCP2_PV_FLAG_DONT_CARE indicates that the outcome of path
+   validation should be ignored entirely. */
+#define NGTCP2_PV_FLAG_DONT_CARE 0x01u
+/* NGTCP2_PV_FLAG_CANCEL_TIMER indicates that the expiry timer is
+   cancelled. */
+#define NGTCP2_PV_FLAG_CANCEL_TIMER 0x02u
+/* NGTCP2_PV_FLAG_FALLBACK_ON_FAILURE indicates that fallback DCID is
+   available in ngtcp2_pv.  If path validation fails, fallback to the
+   fallback DCID.  If path validation succeeds, fallback DCID is
+   retired if it does not equal to the current DCID. */
+#define NGTCP2_PV_FLAG_FALLBACK_ON_FAILURE 0x04u
+/* NGTCP2_PV_FLAG_PREFERRED_ADDR indicates that client is migrating to
+   server's preferred address.  This flag is only used by client. */
+#define NGTCP2_PV_FLAG_PREFERRED_ADDR 0x10u
+
+typedef struct ngtcp2_pv ngtcp2_pv;
+
+ngtcp2_static_ringbuf_def(pv_ents, NGTCP2_PV_MAX_ENTRIES,
+                          sizeof(ngtcp2_pv_entry));
+/*
+ * ngtcp2_pv is the context of a single path validation.
+ */
+struct ngtcp2_pv {
+  const ngtcp2_mem *mem;
+  ngtcp2_log *log;
+  /* dcid is DCID and path this path validation uses. */
+  ngtcp2_dcid dcid;
+  /* fallback_dcid is the usually validated DCID and used as a
+     fallback if this path validation fails. */
+  ngtcp2_dcid fallback_dcid;
+  /* ents is the ring buffer of ngtcp2_pv_entry */
+  ngtcp2_static_ringbuf_pv_ents ents;
+  /* timeout is the duration within which this path validation should
+     succeed. */
+  ngtcp2_duration timeout;
+  /* fallback_pto is PTO of fallback connection. */
+  ngtcp2_duration fallback_pto;
+  /* started_ts is the timestamp this path validation starts. */
+  ngtcp2_tstamp started_ts;
+  /* round is the number of times that probe_pkt_left is reset. */
+  size_t round;
+  /* probe_pkt_left is the number of probe packets containing
+     PATH_CHALLENGE which can be send without waiting for an
+     expiration of a previous flight. */
+  size_t probe_pkt_left;
+  /* flags is bitwise-OR of zero or more of NGTCP2_PV_FLAG_*. */
+  uint8_t flags;
+};
+
+/*
+ * ngtcp2_pv_new creates new ngtcp2_pv object and assigns its pointer
+ * to |*ppv|.  This function makes a copy of |dcid|.  |timeout| is a
+ * duration within which this path validation must succeed.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * NGTCP2_ERR_NOMEM
+ *     Out of memory
+ */
+int ngtcp2_pv_new(ngtcp2_pv **ppv, const ngtcp2_dcid *dcid,
+                  ngtcp2_duration timeout, uint8_t flags, ngtcp2_log *log,
+                  const ngtcp2_mem *mem);
+
+/*
+ * ngtcp2_pv_del deallocates |pv|.  This function frees memory |pv|
+ * points too.
+ */
+void ngtcp2_pv_del(ngtcp2_pv *pv);
+
+/*
+ * ngtcp2_pv_add_entry adds new entry with |data|.  |expiry| is the
+ * expiry time of the entry.
+ */
+void ngtcp2_pv_add_entry(ngtcp2_pv *pv, const uint8_t *data,
+                         ngtcp2_tstamp expiry, uint8_t flags, ngtcp2_tstamp ts);
+
+/*
+ * ngtcp2_pv_full returns nonzero if |pv| is full of ngtcp2_pv_entry.
+ */
+int ngtcp2_pv_full(ngtcp2_pv *pv);
+
+/*
+ * ngtcp2_pv_validate validates that the received |data| matches the
+ * one of the existing entry.  The flag of ngtcp2_pv_entry that
+ * matches |data| is assigned to |*pflags| if this function succeeds.
+ *
+ * This function returns 0 if it succeeds, or one of the following
+ * negative error codes:
+ *
+ * NGTCP2_ERR_PATH_VALIDATION_FAILED
+ *     path validation has failed and must be abandoned
+ * NGTCP2_ERR_INVALID_STATE
+ *     |pv| includes no entry
+ * NGTCP2_ERR_INVALID_ARGUMENT
+ *     |pv| does not have an entry which has |data| and |path|
+ */
+int ngtcp2_pv_validate(ngtcp2_pv *pv, uint8_t *pflags, const uint8_t *data);
+
+/*
+ * ngtcp2_pv_handle_entry_expiry checks expiry of existing entries.
+ */
+void ngtcp2_pv_handle_entry_expiry(ngtcp2_pv *pv, ngtcp2_tstamp ts);
+
+/*
+ * ngtcp2_pv_should_send_probe returns nonzero if new entry can be
+ * added by ngtcp2_pv_add_entry.
+ */
+int ngtcp2_pv_should_send_probe(ngtcp2_pv *pv);
+
+/*
+ * ngtcp2_pv_validation_timed_out returns nonzero if the path
+ * validation fails because of timeout.
+ */
+int ngtcp2_pv_validation_timed_out(ngtcp2_pv *pv, ngtcp2_tstamp ts);
+
+/*
+ * ngtcp2_pv_next_expiry returns the earliest expiry.
+ */
+ngtcp2_tstamp ngtcp2_pv_next_expiry(ngtcp2_pv *pv);
+
+/*
+ * ngtcp2_pv_cancel_expired_timer cancels the expired timer.
+ */
+void ngtcp2_pv_cancel_expired_timer(ngtcp2_pv *pv, ngtcp2_tstamp ts);
+
+#endif /* NGTCP2_PV_H */