apache · moonchen · Jul 8, 2022 · Jul 13, 2022 · Jul 14, 2022 · Aug 4, 2022
diff --git a/configure.ac b/configure.ac
@@ -1818,6 +1818,10 @@ AC_LANG_POP([C++])
 # Right now, the healthcheck plugins requires inotify_init (and friends)
 AM_CONDITIONAL([BUILD_HEALTHCHECK_PLUGIN], [ test "$ac_cv_func_inotify_init" = "yes" ])
 
+use_inotify=0
+AS_IF([test "x$ac_cv_func_inotify_init" = "xyes"], [use_inotify=1])
+AC_SUBST(use_inotify)
+
 #
 # Check for tcmalloc, jemalloc and mimalloc
 TS_CHECK_TCMALLOC
@@ -2262,7 +2266,8 @@ iocore_include_dirs="\
 -I\$(abs_top_srcdir)/iocore/hostdb \
 -I\$(abs_top_srcdir)/iocore/cache \
 -I\$(abs_top_srcdir)/iocore/utils \
--I\$(abs_top_srcdir)/iocore/dns"
+-I\$(abs_top_srcdir)/iocore/dns \
+-I\$(abs_top_srcdir)/iocore/fs"
 
 AC_SUBST([AM_CPPFLAGS])
 AC_SUBST([AM_CFLAGS])
@@ -2310,6 +2315,7 @@ AC_CONFIG_FILES([
   iocore/cache/Makefile
   iocore/dns/Makefile
   iocore/eventsystem/Makefile
+  iocore/fs/Makefile
   iocore/hostdb/Makefile
   iocore/net/Makefile
   iocore/net/quic/Makefile

diff --git a/doc/admin-guide/plugins/s3_auth.en.rst b/doc/admin-guide/plugins/s3_auth.en.rst
@@ -44,7 +44,7 @@ Alternatively, you can store the access key and secret in an external configurat
 
    # remap.config
 
-   ...  @plugin=s3_auth.so @pparam=--config @pparam=s3_auth_v2.config
+   ...  @plugin=s3_auth.so @pparam=--config @pparam=s3_auth_v2.config @pparam=--watch-config @pparam=--ttl=5
 
 
 Where ``s3.config`` could look like::
@@ -94,6 +94,8 @@ The ``s3_auth_v4.config`` config file could look like this::
     v4-include-headers=<comma-separated-list-of-headers-to-be-signed>
     v4-exclude-headers=<comma-separated-list-of-headers-not-to-be-signed>
     v4-region-map=region_map.config
+    watch-config
+    ttl=20
 
 Where the ``region_map.config`` defines the entry-point hostname to region mapping i.e.::
 
@@ -123,6 +125,10 @@ If ``--v4-include-headers`` is not specified all headers except those specified
 
 If ``--v4-include-headers`` is specified only the headers specified will be signed except those specified in ``--v4-exclude-headers``
 
+If ``--watch-config`` is specified, the plugin will reload the config file set in ``--config`` when it changes
+
+If ``--ttl`` is specified, the plugin will cache configs for the specified number of seconds.  During the ttl period, manual config reloads and ``--watch-config`` will not cause the config to be updated.  The default is 60 seconds.  Setting ttl to zero causes all reloads to read from the config file.  This option is useful if the config file is fetched from a service, and you wish to limit the fetch rate.
+
 
 AWS Authentication version 2
 ============================

diff --git a/doc/developer-guide/api/functions/TSFileEventRegister.en.rst b/doc/developer-guide/api/functions/TSFileEventRegister.en.rst
@@ -0,0 +1,85 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed
+   with this work for additional information regarding copyright
+   ownership.  The ASF licenses this file to you under the Apache
+   License, Version 2.0 (the "License"); you may not use this file
+   except in compliance with the License.  You may obtain a copy of
+   the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied.  See the License for the specific language governing
+   permissions and limitations under the License.
+
+.. include:: ../../../common.defs
+
+.. default-domain:: c
+
+TSFileEventRegister
+*******************
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. function:: TSWatchDescriptor TSFileEventRegister(const char *path, TSFileWatchKind kind, TSCont contp)
+
+Description
+===========
+
+Attempt to register a watch on a file or directory.  :arg:`contp` will be called when
+the OS reports a change in the file system at :arg:`path`.
+
+Types
+=====
+
+.. enum:: TSFileWatchKind
+
+   The kind of changes to watch on the path.
+
+   ..  enumerator:: TS_WATCH_CREATE
+
+      Only valid on directories.  :arg:`contp` is called after a file or directory has been
+      created under :arg:`path`.  Some operating systems, such as Linux, will supply a file
+      name of the newly created file or directory.  This name is passed to :arg:`contp` when
+      it's available.
+
+   ..  enumerator:: TS_WATCH_DELETE
+
+      Valid on files and directories.  :arg:`contp` is called after :arg:`path` is deleted.
+
+   ..  enumerator:: TS_WATCH_MODIFY
+
+      Valid on files and directories.  :arg:`contp` is called after :arg:`path` has been modified.
+
+.. struct:: TSFileWatchData
+
+   A class that holds information for the callback.  :arg:`contp` will be called back with
+   :arg:`edata` pointing to one of these.
+
+   ..  member:: TSWatchDescriptor wd
+
+      The watch descriptor for that was previously returned from :func:`TSFileEventRegister`.
+
+   ..  member:: const char *name
+
+      Only sometimes populated for :enumerator:`TS_WATCH_CREATE`.  The name of the created
+      file.  Note that this name is not always available.  When it's unavailable, the value will
+      be :code:`nullptr`.
+
+.. type:: TSWatchDescriptor
+
+   An opaque type that identifies a file system watch.
+
+Return Value
+============
+
+Returns a TSWatchDescriptor on success, or -1 on failure.  The caller should store the
+returned watch descriptor  .
+
diff --git a/doc/developer-guide/api/functions/TSFileEventUnregister.en.rst b/doc/developer-guide/api/functions/TSFileEventUnregister.en.rst
@@ -0,0 +1,37 @@
+.. Licensed to the Apache Software Foundation (ASF) under one or more
+   contributor license agreements.  See the NOTICE file distributed
+   with this work for additional information regarding copyright
+   ownership.  The ASF licenses this file to you under the Apache
+   License, Version 2.0 (the "License"); you may not use this file
+   except in compliance with the License.  You may obtain a copy of
+   the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+   implied.  See the License for the specific language governing
+   permissions and limitations under the License.
+
+.. include:: ../../../common.defs
+
+.. default-domain:: c
+
+TSFileEventUnregister
+*********************
+
+Synopsis
+========
+
+.. code-block:: cpp
+
+    #include <ts/ts.h>
+
+.. function:: void TSFileEventUnregister(TSWatchDescriptor wd)
+
+Description
+===========
+
+Unregister a watch that was registered by :func:`TSFileEventRegister`.  :arg:`wd` is the return value from :func:`TSFileEventRegister`.
+
diff --git a/doc/developer-guide/testing/blackbox-testing.en.rst b/doc/developer-guide/testing/blackbox-testing.en.rst
@@ -262,6 +262,7 @@ Condition Testing
         - TS_HAS_128BIT_CAS
         - TS_HAS_TESTS
         - TS_HAS_WCCP
+        - TS_USE_INOTIFY
 
 
 Examples:

diff --git a/include/ts/apidefs.h.in b/include/ts/apidefs.h.in
@@ -554,7 +554,12 @@ typedef enum {
   TS_EVENT_SSL_CLIENT_HELLO  = 60207,
   TS_EVENT_SSL_SECRET        = 60208,
 
-  TS_EVENT_MGMT_UPDATE = 60300
+  TS_EVENT_MGMT_UPDATE = 60300,
+
+  TS_EVENT_FILE_CREATED = 60400,
+  TS_EVENT_FILE_UPDATED = 60401,
+  TS_EVENT_FILE_DELETED = 60402,
+  TS_EVENT_FILE_IGNORED = 60403
 } TSEvent;
 #define TS_EVENT_HTTP_READ_REQUEST_PRE_REMAP TS_EVENT_HTTP_PRE_REMAP /* backwards compat */
 
@@ -1460,6 +1465,13 @@ namespace ts
 }
 #endif
 
+typedef int TSWatchDescriptor;
+typedef enum { TS_WATCH_CREATE, TS_WATCH_DELETE, TS_WATCH_MODIFY } TSFileWatchKind;
+typedef struct {
+  TSWatchDescriptor wd;
+  const char *name;
+} TSFileWatchData;
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/include/ts/ts.h b/include/ts/ts.h
@@ -2755,6 +2755,21 @@ tsapi void TSHostStatusSet(const char *hostname, const size_t hostname_len, TSHo
 tsapi bool TSHttpTxnCntlGet(TSHttpTxn txnp, TSHttpCntlType ctrl);
 tsapi TSReturnCode TSHttpTxnCntlSet(TSHttpTxn txnp, TSHttpCntlType ctrl, bool data);
 
+/*
+ * Get notified for file system events
+ *
+ * TODO: Fix multiple plugins watching the same path.
+ *
+ * The edata (a.k.a. cookie) field of the continuation handler will contain information
+ * depending on the type of file event.  edata is always a pointer to a TSFileWatchData.
+ * If the event is TS_EVENT_FILE_CREATED, and ATS is running on Linux, name is a pointer
+ * to a null-terminated string containing the file name.  Otherwise, name is a nullptr.
+ * wd is the watch descriptor for the event.
+ *
+ */
+tsapi TSWatchDescriptor TSFileEventRegister(const char *path, TSFileWatchKind kind, TSCont contp);
+tsapi void TSFileEventUnregister(TSWatchDescriptor wd);
+
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
diff --git a/include/tscore/ink_config.h.in b/include/tscore/ink_config.h.in
@@ -83,6 +83,7 @@
 #define TS_HAS_TLS_EARLY_DATA @has_tls_early_data@
 #define TS_HAS_TLS_SESSION_TICKET @has_tls_session_ticket@
 #define TS_HAS_VERIFY_CERT_STORE @has_verify_cert_store@
+#define TS_USE_INOTIFY @use_inotify@
 
 #define TS_USE_HRW_GEOIP @use_hrw_geoip@
 #define TS_USE_HRW_MAXMINDDB @use_hrw_maxminddb@

diff --git a/iocore/Makefile.am b/iocore/Makefile.am
@@ -16,4 +16,4 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
-SUBDIRS = eventsystem net aio dns hostdb utils cache
+SUBDIRS = eventsystem net aio dns hostdb utils cache fs