cache.config -> cache.yaml

configs/cache.config.default

@@ -1,6 +1,9 @@
 #
 # cache.config
 #
+# Legacy configuration. New deployments should use cache.yaml. To continue
+# using this file, set proxy.config.cache.control.filename to cache.config.
+#
 # Documentation:
 #    https://docs.trafficserver.apache.org/en/latest/admin-guide/files/cache.config.en.html
 #

configs/cache.yaml.default

@@ -0,0 +1,36 @@
+# cache.yaml
+#
+# Documentation:
+#    https://docs.trafficserver.apache.org/en/latest/admin-guide/files/cache.yaml.en.html
+#
+# Rules are evaluated from top to bottom. Only the first matching rule is
+# applied to a request.
+#
+# cache:
+#   - match:
+#       # A rule may have one primary match key:
+#       # dest_host, dest_domain, dest_ip, url_regex, or host_regex.
+#       dest_domain: www.example.com
+#
+#       # Optional secondary match keys:
+#       # port, scheme, prefix, suffix, method, time, src_ip,
+#       # incoming_port, tag, and internal.
+#       scheme: http
+#
+#     action:
+#       # cache may be "never" or "standard".
+#       cache: standard
+#
+#       # Optional duration actions:
+#       # revalidate, pin_in_cache, and ttl_in_cache.
+#       revalidate: 2h
+#
+#       # Optional boolean actions:
+#       # ignore_no_cache, ignore_client_no_cache, and
+#       # ignore_server_no_cache.
+#       ignore_server_no_cache: false
+#
+#       # Optional override matching the records.yaml setting of the same name.
+#       # cache_responses_to_cookies: 0
+
+cache: []

configs/records.yaml.default.in

@@ -76,7 +76,7 @@ records:
 ##############################################################################
 # Cache control. Docs:
 #    https://docs.trafficserver.apache.org/en/latest/admin-guide/files/records.yaml.en.html#cache-control
-#    https://docs.trafficserver.apache.org/en/latest/admin-guide/files/cache.config.en.html
+#    https://docs.trafficserver.apache.org/en/latest/admin-guide/files/cache.yaml.en.html
 ##############################################################################
       ignore_client_cc_max_age: 1
 

doc/admin-guide/configuration/cache-basics.en.rst

@@ -137,13 +137,13 @@ by checking the following conditions in order:
    maximum and minimum freshness limit. Refer to
    `Setting Absolute Freshness Limits`_.
 
--  **Checking revalidate rules in** :file:`cache.config`
+-  **Checking revalidate rules in** :file:`cache.yaml`
 
    Revalidate rules apply freshness limits to specific HTTP objects. You
    can set freshness limits for objects originating from particular
    domains or IP addresses, objects with URLs that contain specified
    regular expressions, objects requested by particular clients, and so
-   on. Refer to :file:`cache.config`.
+   on. Refer to :file:`cache.yaml`.
 
 Modifying Aging Factor for Freshness Computations
 -------------------------------------------------
@@ -354,7 +354,7 @@ one of the following options:
     Revalidate all HTTP objects without ``Expires`` or ``Cache-Control`` headers.
 
 To configure how Traffic Server revalidates objects in the cache, you
-can set specific revalidation rules in :file:`cache.config`.
+can set specific revalidation rules in :file:`cache.yaml`.
 
 To configure revalidation options
 
@@ -435,10 +435,16 @@ To set cache pinning rules:
 
         CONFIG proxy.config.cache.permit.pinning INT 1
 
-#. Add a rule in :file:`cache.config` for each URL you want Traffic Server to
-   pin in the cache. For example::
+#. Add a rule in :file:`cache.yaml` for each URL you want Traffic Server to
+   pin in the cache. For example:
 
-      url_regex=^https?://(www.)?apache.org/dev/ pin-in-cache=12h
+   .. code-block:: yaml
+
+      cache:
+        - match:
+            url_regex: ^https?://(www.)?apache.org/dev/
+          action:
+            pin_in_cache: 12h
 
 #. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
 
@@ -587,14 +593,14 @@ You can configure Traffic Server to do the following:
 -  Cache objects served in response to the ``Cookie:`` header. Refer to
    `Caching Cookied Objects`_.
 
--  Observe ``never-cache`` rules in :file:`cache.config`.
+-  Observe ``cache: never`` rules in :file:`cache.yaml`.
 
 Disabling HTTP Object Caching
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 By default, Traffic Server caches all HTTP objects except those for
-which you have set ``never-cache`` as :ref:`action rules <cache-config-format-action>`
-in :file:`cache.config`. You can disable HTTP object caching so that all HTTP
+which you have set ``cache: never`` as a :ref:`cache.yaml action
+<cache-yaml-actions>`. You can disable HTTP object caching so that all HTTP
 objects are served directly from the origin server and never cached, as
 detailed below.
 
@@ -668,10 +674,16 @@ headers.
 
 To force document caching:
 
-#. Add a rule for each URL you want Traffic Server to pin to the cache
-   :file:`cache.config`::
+#. Add a rule for each URL you want Traffic Server to force into
+   :file:`cache.yaml`:
+
+   .. code-block:: yaml
 
-       url_regex=^https?://(www.)?apache.org/dev/ ttl-in-cache=6h
+      cache:
+        - match:
+            url_regex: ^https?://(www.)?apache.org/dev/
+          action:
+            ttl_in_cache: 6h
 
 #. Run the command :option:`traffic_ctl config reload` to apply the configuration changes.
 

doc/admin-guide/files/cache.config.en.rst

@@ -22,6 +22,14 @@
 cache.config
 ************
 
+.. deprecated:: 11.0
+
+   Use :file:`cache.yaml` for new configurations. Convert an existing file with
+   ``traffic_ctl config convert cache cache.config cache.yaml``. Review
+   overlapping rules after conversion because :file:`cache.yaml` uses
+   first-match semantics. The legacy parser remains available by setting
+   ``proxy.config.cache.control.filename`` to ``cache.config``.
+
 The :file:`cache.config` file allows you to overrule the origin's cache
 policies. You can add caching rules to specify the following:
 
@@ -280,4 +288,3 @@ Force a specific regex to be in cache between 7-11pm of the server's time for
 Prevent objects from being evicted from cache::
 
    url_regex=example.com/game/.* pin-in-cache=1h
-

doc/admin-guide/files/cache.yaml.en.rst

@@ -0,0 +1,177 @@
+.. 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
+
+.. configfile:: cache.yaml
+
+cache.yaml
+**********
+
+The :file:`cache.yaml` file allows administrators to override origin cache
+policies for selected requests. It replaces the legacy :file:`cache.config`
+format. After modifying the file, run :option:`traffic_ctl config reload` to
+apply the changes.
+
+Generally, origin-provided ``Cache-Control`` headers are preferable because the
+origin can make finer-grained decisions. Use :file:`cache.yaml` for policies
+that must be enforced by the proxy.
+
+Format
+======
+
+The top-level ``cache`` key contains a sequence of rules. Each rule has an
+optional ``match`` map and a required ``action`` map:
+
+.. code-block:: yaml
+
+   cache:
+     - match:
+         dest_domain: example.com
+         suffix: js
+       action:
+         revalidate: 6h
+         ignore_server_no_cache: true
+
+     - match:
+         dest_domain: example.com
+       action:
+         revalidate: 1h
+
+A rule without a ``match`` map matches every request.
+
+Matching
+========
+
+A ``match`` map may contain at most one primary match key:
+
+================= ============================================================
+Key               Meaning
+================= ============================================================
+``dest_host``     Exact destination host name.
+``dest_domain``   Destination domain name.
+``dest_ip``       Destination IP address or range.
+``url_regex``     Regular expression matched against the request URL.
+``host_regex``    Regular expression matched against the destination host.
+================= ============================================================
+
+It may also contain any of these secondary match keys:
+
+================= ============================================================
+Key               Meaning
+================= ============================================================
+``port``          Request URL port or port range.
+``scheme``        Request URL scheme, such as ``http`` or ``https``.
+``prefix``        Prefix of the URL path.
+``suffix``        Suffix of the URL path. Comma-separated values are allowed.
+``method``        HTTP request method.
+``time``          Server-local 24-hour time range, such as ``08:00-14:00``.
+``src_ip``        Client IP address or range.
+``incoming_port`` Local port on which the request was received.
+``tag``           Tag supplied by an internal caller.
+``internal``      Whether the transaction originated from an internal API.
+================= ============================================================
+
+First Matching Rule
+-------------------
+
+Rules are evaluated in the order listed, and only the first matching rule is
+applied. Actions from later rules are not combined with the selected rule.
+Place specific rules before general rules:
+
+.. code-block:: yaml
+
+   cache:
+     - match:
+         dest_domain: example.com
+         suffix: jpeg
+       action:
+         revalidate: 6h
+
+     - match:
+         dest_domain: example.com
+       action:
+         revalidate: 1h
+
+Here JPEG objects use a six-hour revalidation interval, while other objects in
+the domain use one hour.
+
+.. _cache-yaml-actions:
+
+Actions
+========
+
+The ``action`` map supports the following keys:
+
+============================== ===============================================
+Key                            Meaning
+============================== ===============================================
+``cache``                      ``never`` prevents caching; ``standard`` uses
+                               normal cacheability rules.
+``revalidate``                 How long matching cached objects remain fresh.
+``pin_in_cache``               How long matching objects are protected from
+                               eviction.
+``ttl_in_cache``               Forces matching objects into cache for the
+                               specified duration.
+``ignore_no_cache``            Ignores client and server no-cache directives.
+``ignore_client_no_cache``     Ignores client no-cache directives.
+``ignore_server_no_cache``     Ignores origin no-cache directives.
+``cache_responses_to_cookies`` Overrides
+                               :ts:cv:`proxy.config.http.cache.cache_responses_to_cookies`
+                               with an integer from 0 through 4.
+============================== ===============================================
+
+Durations accept days, hours, minutes, and seconds, including mixed values such
+as ``1d2h`` or ``15m20s``. A rule cannot combine ``cache: never`` with
+``ttl_in_cache`` because the two actions conflict.
+
+Multiple actions may be set by one rule:
+
+.. code-block:: yaml
+
+   cache:
+     - match:
+         dest_domain: example.com
+         prefix: /assets/
+       action:
+         ttl_in_cache: 1d
+         pin_in_cache: 2h
+         cache_responses_to_cookies: 0
+
+Migration from cache.config
+===========================
+
+Use :option:`traffic_ctl config convert` to convert an existing
+:file:`cache.config` file:
+
+.. code-block:: bash
+
+   traffic_ctl config convert cache cache.config cache.yaml
+
+Use ``-`` as the output file to preview the conversion on standard output:
+
+.. code-block:: bash
+
+   traffic_ctl config convert cache cache.config -
+
+The converter preserves rule order and combines the directive and any tweaks
+from each legacy line into one YAML action map. Review overlapping rules before
+deploying the result: legacy :file:`cache.config` rules accumulate actions from
+every match, whereas :file:`cache.yaml` applies only the first matching rule.
+
+The line-based parser remains available during migration. Set
+``proxy.config.cache.control.filename`` to ``cache.config`` to use it.

doc/admin-guide/files/index.en.rst

@@ -26,6 +26,7 @@ Configuration Files
    :hidden:
 
    cache.config.en
+   cache.yaml.en
    hosting.config.en
    ip_allow.yaml.en
    logging.yaml.en
@@ -42,10 +43,13 @@ Configuration Files
    strategies.yaml.en
    jsonrpc.yaml.en
 
-:doc:`cache.config.en`
+:doc:`cache.yaml.en`
    Defines if, how, and for what durations |TS| caches objects, based on
    destinations, clients, URL components, and more.
 
+:doc:`cache.config.en`
+   Documents the deprecated line-based cache rule format.
+
 :doc:`hosting.config.en`
    Allows |TS| administrators to assign cache volumes to specific origin
    servers or domains.

doc/admin-guide/files/records.yaml.en.rst

@@ -2749,7 +2749,7 @@ Cache Control
 .. ts:cv:: CONFIG proxy.config.cache.permit.pinning INT 0
    :reloadable:
 
-   When enabled (``1``), |TS| will keep certain HTTP objects in the cache for a certain time as specified in cache.config.
+   When enabled (``1``), |TS| will keep certain HTTP objects in the cache for a certain time as specified in cache.yaml.
 
 .. ts:cv:: CONFIG proxy.config.cache.hit_evacuate_percent INT 0
 

doc/admin-guide/plugins/txn_box/dev/design.en.rst

@@ -59,7 +59,7 @@ To avoid that, however, required the new URL rewrite configuration to be much mo
 general such that it could perform the functions of these other configurations, including
 
 *  hosting.config
-*  cache.config
+*  cache.yaml
 *  parent.config
 *  The `header_rewrite` plugin.
 *  The `regex_remap` plugin.

doc/admin-guide/storage/index.en.rst

@@ -64,7 +64,7 @@ You can perform the following cache configuration tasks:
 -  Override cache directives for a requested domain name, regex on a url,
    hostname or ip, with extra filters for time, port, method of the request,
    and more. ATS can be configured to never cache, always cache,
-   ignore no-cache directives, etc. These are configured in :file:`cache.config`.
+   ignore no-cache directives, etc. These are configured in :file:`cache.yaml`.
 
 The RAM Cache
 =============