From 43448f664ea0b49ccb4ded59f3ca3d8523947ced Mon Sep 17 00:00:00 2001
From: Amna <amna.snene@savoirfairelinux.com>
Date: Wed, 11 Sep 2024 17:20:13 -0400
Subject: [PATCH] doc/mappings: add a description of the mapping state machine
Change-Id: I65f7c277e32b71e45f4eaf08be4df4146d823348
---
include/upnp/mapping.h | 21 +++++++++++++++++++++
1 file changed, 21 insertions(+)
diff --git a/include/upnp/mapping.h b/include/upnp/mapping.h
index f4398b7..0468352 100644
--- a/include/upnp/mapping.h
+++ b/include/upnp/mapping.h
@@ -31,6 +31,27 @@ namespace upnp {
using sys_clock = std::chrono::system_clock;
enum class PortType { TCP, UDP };
+
+/**
+ * State Machine:
+ *
+ * - PENDING: Initial state when a mapping is requested by the client.
+ * - IN_PROGRESS: Intermediate state while the mapping is being requested from an IGD.
+ * - OPEN: State when the mapping is successfully established.
+ * - FAILED: State when the mapping fails or is invalidated.
+ *
+ * State Transitions:
+ *
+ * - PENDING -> IN_PROGRESS: When the mapping request is sent to the IGD.
+ * - PENDING -> FAILED: When there is no valid IGD and it's not during the IGD discovery phase.
+ * - IN_PROGRESS -> OPEN: When the mapping is successfully established.
+ * - IN_PROGRESS -> FAILED: When the mapping fails.
+ * - OPEN -> FAILED: When the IGD becomes invalid or the mapping is removed.
+ * - FAILED -> PENDING: When auto-update is enabled and there is no valid IGD.
+ * - FAILED -> unregistered: When auto-update is disabled.
+ *
+ * If auto-update is enabled but there is a valid IGD, the mapping will be unregistered and a new mapping of the same type will be requested.
+ */
enum class MappingState { PENDING, IN_PROGRESS, FAILED, OPEN };
enum class NatProtocolType;
--
GitLab