From c145c8047a187f94d805830ef47ca2199e1fc3ab Mon Sep 17 00:00:00 2001
From: Kory Draughn <korydraughn@renci.org>
Date: Sun, 25 Aug 2024 11:10:31 -0400
Subject: [PATCH] [273] Document how iRODS manages connections and other
 things.

---
 docs/system_overview/connections.md | 24 ++++++++++++++++++++++++
 mkdocs.yml                          |  1 +
 2 files changed, 25 insertions(+)
 create mode 100644 docs/system_overview/connections.md

diff --git a/docs/system_overview/connections.md b/docs/system_overview/connections.md
new file mode 100644
index 0000000..e74920d
--- /dev/null
+++ b/docs/system_overview/connections.md
@@ -0,0 +1,24 @@
+#
+
+## Server-to-Server Connections
+
+iRODS is a distributed system that enables users to manage data stored geographically across disparate storage technologies. iRODS achieves this by redirecting client requests to the appropriate server. This happens automatically and does not require interaction from the client or admin.
+
+The following is true after a redirect of the client request:
+
+    - Server-to-Server connections persist after creation for the lifetime of the agent
+    - Server-to-Server connections represent the user who triggered their creation
+    - Server-to-Server connections are disconnected on agent shutdown
+
+## Long-Running Connections
+
+- agents do not see ALL changes to policy
+
+## Connection Pooling
+
+- why
+    - improve performance by avoiding tcp connection startup/shutdown
+    - target audience is developers building irods client which runs as a server
+- how
+    - create multiple client connections
+    - use `rc_switch_user` and optionally `rc_check_auth_credenticals`
diff --git a/mkdocs.yml b/mkdocs.yml
index 62afc47..1dba138 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -54,6 +54,7 @@ nav:
     - Process Model: 'system_overview/process_model.md'
     - Control Plane: 'system_overview/control_plane.md'
     - Configuration: 'system_overview/configuration.md'
+    - Connections: 'system_overview/connections.md'
     - SSL: 'system_overview/ssl.md'
     - Users and Permissions: 'system_overview/users_and_permissions.md'
     - GenQuery: 'system_overview/genquery.md'