This is an automated email from the ASF dual-hosted git repository.
zrhoffman pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git
The following commit(s) were added to refs/heads/master by this push:
new 97bf213 Add/update documentation for content invalidation jobs in TO
API v4 (#6342)
97bf213 is described below
commit 97bf21374f37b69b644befb4cdc1791e72264fd1
Author: ocket8888 <[email protected]>
AuthorDate: Mon Nov 15 14:31:04 2021 -0700
Add/update documentation for content invalidation jobs in TO API v4 (#6342)
* Add jobs overview section
* Add styling for kbd elements in the docs
* Create glossary term for jobs, link it everywhere
I didn't worry too much about the APIv4 docs, since they'll need to be
rebased anyway.
* Fix incorrect plurality, broken tables
* Fix rendering of keyboard key elements containing only whitespace
* Simplify string formatting of new jobs, add Godocs and example/test
* Add section links, missing TTL alias
* Add a description of the new "semi-global" "refetch_enabled" Parameter
* Update the v4 documentation for /jobs
* Move admonition about HTTP caching support to the overview page
* Update the "quick how-to" guide for content invalidation jobs
* Fix rendering errors in TP 'using' section
* Fix extraneous 'Content' and incorrect plurality
* Fix 'term' role in response payload examples
* Fix Asset URL labled immutable in the overview
* Remove extraneous '.'
* Remove stutter in model reference
* Fix incorrect response example for v4/jobs
---
docs/source/_static/theme_overrides.css | 14 +
.../admin/quick_howto/content_invalidation.rst | 12 +-
.../admin/quick_howto/content_invalidation/01.png | Bin 42695 -> 155334 bytes
.../admin/quick_howto/content_invalidation/03.png | Bin 32869 -> 158245 bytes
.../admin/quick_howto/content_invalidation/04.png | Bin 0 -> 43711 bytes
.../admin/traffic_portal/usingtrafficportal.rst | 18 +-
docs/source/api/v2/deliveryservices_request.rst | 2 +-
docs/source/api/v2/jobs.rst | 133 ++++----
.../api/v2/servers_hostname_update_status.rst | 8 +-
docs/source/api/v3/deliveryservices_request.rst | 2 +-
docs/source/api/v3/jobs.rst | 129 ++++----
.../api/v3/servers_hostname_update_status.rst | 8 +-
docs/source/api/v4/jobs.rst | 354 +++++++++------------
.../api/v4/servers_hostname_update_status.rst | 8 +-
docs/source/glossary.rst | 8 +
docs/source/overview/delivery_service_requests.rst | 1 +
docs/source/overview/jobs.rst | 137 ++++++++
docs/source/overview/profiles_and_parameters.rst | 24 +-
docs/source/tools/atstccfg.rst | 2 +-
lib/go-tc/invalidationjobs.go | 24 +-
lib/go-tc/invalidationjobs_test.go | 17 +
21 files changed, 531 insertions(+), 370 deletions(-)
diff --git a/docs/source/_static/theme_overrides.css
b/docs/source/_static/theme_overrides.css
index ebdf46e..c71faea 100644
--- a/docs/source/_static/theme_overrides.css
+++ b/docs/source/_static/theme_overrides.css
@@ -99,3 +99,17 @@ ul, ol, ul > li, ol > li {
ul > li > p, ol > li > p {
margin: 0;
}
+
+kbd {
+ display: inline-block;
+ padding: 4px 5px;
+ font: smaller ui-monospace, SFMono-Regular, SF Mono, Menlo, Consolas,
Liberation Mono, monospace;
+ line-height: 10px;
+ vertical-align: middle;
+ background-color: white;
+ border: solid 1px rgba(99,110,123,0.4);
+ border-radius: 6px;
+ box-shadow: inset 0 -1px 0 rgba(99,110,123,0.4);
+ min-height: 1.5em;
+ min-width: 1.2em;
+}
diff --git a/docs/source/admin/quick_howto/content_invalidation.rst
b/docs/source/admin/quick_howto/content_invalidation.rst
index 7e5061c..cb8270c 100644
--- a/docs/source/admin/quick_howto/content_invalidation.rst
+++ b/docs/source/admin/quick_howto/content_invalidation.rst
@@ -22,8 +22,6 @@ Invalidating content on the CDN is sometimes necessary when
the :term:`Origin` w
.. impl-detail:: Given the size of a typical Traffic Control CDN and the
amount of content that can be cached in it, removing the content from all the
caches may take a long time. To speed up content invalidation, Traffic Control
does not try to remove the content from the caches, but it makes the content
inaccessible using the `regex_revalidate plugin for Apache Traffic Server
<https://docs.trafficserver.apache.org/en/8.0.x/admin-guide/plugins/regex_revalidate.en.html>`_.
This forces a [...]
-.. Warning:: This method forces :term:`cache servers` to "re-validate"
content, so in order to work properly the :term:`Origin` needs to support
revalidation according to section 4.3.2 of :rfc:`7234`.
-
To invalidate content for a specific :term:`Delivery Service`, follow these
steps:
#. Select the desired :term:`Delivery Service` from the
:ref:`tp-services-delivery-service` view of Traffic Portal
@@ -42,10 +40,18 @@ To invalidate content for a specific :term:`Delivery
Service`, follow these step
Select 'Manage Invalidation Requests'
-#. Click/tap on the :guilabel:`+` button to open the submission form for a new
content invalidation. Fill out this form. The "Path Regex" field should be a
`PCRE <http://www.pcre.org/>`_-compatible regular expression that matches all
content that must be invalidated - and should **not** match any content that
must *not* be invalidated. "TTL (hours)" specifies the number of hours for
which the invalidation should remain active. Best practice is to set this to
the same as the content's cac [...]
+#. From the :guilabel:`More` drop-down menu on this page, select
:menuselection:`Create Invalidation Request`
.. figure:: content_invalidation/03.png
:align: center
+ :alt: The 'Create Invalidation Request' option under 'More'
+
+ Select 'Create Invalidation Request'
+
+#. Fill out this form. The "Path Regex" field should be a `PCRE
<http://www.pcre.org/>`_-compatible regular expression that matches all content
that must be invalidated - and should **not** match any content that must *not*
be invalidated. "TTL (hours)" specifies the number of hours for which the
invalidation should remain active. Best practice is to set this to the same as
the content's cache lifetime (typically set in the :term:`Origin`'s
``Cache-Control`` response header). :ref:`job-i [...]
+
+ .. figure:: content_invalidation/04.png
+ :align: center
:alt: The new content invalidation submission form
The 'new content invalidation submission' Form
diff --git a/docs/source/admin/quick_howto/content_invalidation/01.png
b/docs/source/admin/quick_howto/content_invalidation/01.png
index d0b94e2..fb11981 100644
Binary files a/docs/source/admin/quick_howto/content_invalidation/01.png and
b/docs/source/admin/quick_howto/content_invalidation/01.png differ
diff --git a/docs/source/admin/quick_howto/content_invalidation/03.png
b/docs/source/admin/quick_howto/content_invalidation/03.png
index 83d8935..098349a 100644
Binary files a/docs/source/admin/quick_howto/content_invalidation/03.png and
b/docs/source/admin/quick_howto/content_invalidation/03.png differ
diff --git a/docs/source/admin/quick_howto/content_invalidation/04.png
b/docs/source/admin/quick_howto/content_invalidation/04.png
new file mode 100644
index 0000000..40862b6
Binary files /dev/null and
b/docs/source/admin/quick_howto/content_invalidation/04.png differ
diff --git a/docs/source/admin/traffic_portal/usingtrafficportal.rst
b/docs/source/admin/traffic_portal/usingtrafficportal.rst
index 2858c94..f0adce7 100644
--- a/docs/source/admin/traffic_portal/usingtrafficportal.rst
+++ b/docs/source/admin/traffic_portal/usingtrafficportal.rst
@@ -645,21 +645,23 @@ Tools
Invalidate Content
------------------
-Here, specific assets can be invalidated in all caches of a :term:`Delivery
Service`, forcing content to be updated from the origin. Specifically, this
*doesn't* mean that :term:`cache servers` will immediately remove items from
their caches, but rather will fetch new copies whenever a request is made
matching the 'Asset URL' regular expression. This behavior persists until the
Invalidate Content Job's :abbr:`TTL (Time To Live)` expires.
+Here, specific assets can be invalidated in all caches of a :term:`Delivery
Service`, forcing content to be updated from the origin. Specifically, this
*doesn't* mean that :term:`cache servers` will immediately remove items from
their caches, but rather will fetch new copies whenever a request is made
matching the 'Asset URL' regular expression. This behavior persists until the
:term:`Content Invalidation Job`'s :ref:`job-ttl` expires.
-.. Warning:: This method forces :term:`cache servers` to "re-validate"
content, so in order to work properly the :term:`Origin` needs to support
revalidation according to section 4.3.2 of :rfc:`7234`.
+.. warning:: This method forces :term:`cache servers` to "re-validate"
content, so in order to work properly the :term:`Origin` needs to support
revalidation according to section 4.3.2 of :rfc:`7234`.
Each entry in the table on this page has the following fields:
-:term:`Delivery Service`: The :term:`Delivery Service` to which to apply this
Invalidate Content Job
-:Asset URL: A URL or regular expression which describes the asset(s) to
be invalidated
-:Parameters: So far, the only use for this is setting a :abbr:`TTL (Time
To Live)` over which the Invalidate Content Job shall remain active
-:Start: An effective start time until which the job is delayed
-:Created By: The user name of the person who created this Invalidate
Content Job
+:Delivery Service: The :term:`Delivery Service` to which to apply this
:term:`Content Invalidation Job`
+:Asset URL: A URL or regular expression which describes the asset(s)
to be invalidated
+:TTL (Hours): A :abbr:`TTL (Time To Live)` (as a number of hours) over
which the :term:`Content Invalidation Job` shall remain active
+:Start: An effective start time until which the :term:`job` is
delayed
+:Expires: The date/time at which the :term:`Content Invalidation
Job` will end (effectively "Start" plus "TTL (Hours)")
+:Created By: The user name of the person who created this
:term:`Content Invalidation Job`
+:Invalidation Type: The :ref:`job-invalidation-type` of this :term:`Content
Invalidation Job`
Invalidate content includes the ability to (where applicable):
-- create a new invalidate content job
+- create a new :term:`Content Invalidation Job`
.. _tp-tools-generate-iso:
diff --git a/docs/source/api/v2/deliveryservices_request.rst
b/docs/source/api/v2/deliveryservices_request.rst
index 05d91b9..c9a372d 100644
--- a/docs/source/api/v2/deliveryservices_request.rst
+++ b/docs/source/api/v2/deliveryservices_request.rst
@@ -36,7 +36,7 @@ Request Structure
-----------------
:details: An object describing the actual parameters for the Delivery Service
request
- :customer: Name of the customer associated with the :term:`Delivery
Service` - must only contain alphanumeric characters and the characters
:kbd:`@`, :kbd:`!`, :kbd:`#`, :kbd:`$`, :kbd:`%`, :kbd:`^`, :kbd:`&`, :kbd:`*`,
:kbd:`(`, :kbd:`)`, :kbd:`[`, :kbd:`]`, :kbd:`.`, :kbd:` `, and :kbd:`-`
+ :customer: Name of the customer associated with the :term:`Delivery
Service` - must only contain alphanumeric characters and the characters
:kbd:`@`, :kbd:`!`, :kbd:`#`, :kbd:`$`, :kbd:`%`, :kbd:`^`, :kbd:`&`, :kbd:`*`,
:kbd:`(`, :kbd:`)`, :kbd:`[`, :kbd:`]`, :kbd:`.`, :kbd:`\ `, and :kbd:`-`
.. versionchanged:: ATCv6
Prior to ATC version 6, this field had no restrictions.
diff --git a/docs/source/api/v2/jobs.rst b/docs/source/api/v2/jobs.rst
index 58bcea5..487996b 100644
--- a/docs/source/api/v2/jobs.rst
+++ b/docs/source/api/v2/jobs.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Retrieve content invalidation jobs.
+Retrieve :term:`Content Invalidation Jobs`.
:Auth. Required: Yes
:Roles Required: None\ [#tenancy]_
@@ -34,23 +34,24 @@ Request Structure
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name | Required | Description
|
+======================+==========+==================================================================================================================================================================+
- | assetUrl | no | Return only invalidation jobs that
operate on URLs by matching this regular expression
|
+ | assetUrl | no | Return only :term:`Content
Invalidation Jobs` that operate on URLs by matching this regular expression
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | cdn | no | Return only invalidation jobs for
delivery services with this CDN name
|
+ | cdn | no | Return only :term:`Content
Invalidation Jobs` for delivery services with this CDN name
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | createdBy | no | Return only invalidation jobs that
were created by the user with this username
|
+ | createdBy | no | Return only :term:`Content
Invalidation Jobs` that were created by the user with this username
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | deliveryService | no | Return only invalidation jobs that
operate on the :term:`Delivery Service` with this :ref:`ds-xmlid`
|
+ | deliveryService | no | Return only :term:`Content
Invalidation Jobs` that operate on the :term:`Delivery Service` with this
:ref:`ds-xmlid` |
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | dsId | no | Return only invalidation jobs
pending on the :term:`Delivery Service` identified by this integral, unique
identifier |
+ | dsId | no | Return only :term:`Content
Invalidation Jobs` pending on the :term:`Delivery Service` identified by this
integral, unique identifier |
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | id | no | Return only the single invalidation
job identified by this integral, unique identifer
|
+ | id | no | Return only the single
:term:`Content Invalidation Job` identified by this integral, unique identifer
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | keyword | no | Return only invalidation jobs that
have this "keyword" - only "PURGE" should exist
|
+ | keyword | no | Return only :term:`Content
Invalidation Jobs` that have this "keyword" - only "PURGE" should exist
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | maxRevalDurationDays | no | Return only invalidation jobs with
a startTime that is within the window defined by the ``maxRevalDurationDays``
:term:`Parameter` in :ref:`the-global-profile` |
+ | maxRevalDurationDays | no | Return only :term:`Content
Invalidation Jobs` with a startTime that is within the window defined by the
``maxRevalDurationDays`` :term:`Parameter` in |
+ | | | :ref:`the-global-profile`
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | userId | no | Return only invalidation jobs
created by the user identified by this integral, unique identifier
|
+ | userId | no | Return only :term:`Content
Invalidation Jobs` created by the user identified by this integral, unique
identifier |
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -68,16 +69,16 @@ Request Structure
Response Structure
------------------
:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-:createdBy: The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates
-:id: An integral, unique identifier for this job
-:keyword: A keyword that represents the operation being performed by
the job:
+:createdBy: The username of the user who initiated the :term:`job`
+:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this :term:`job` operates
+:id: An integral, unique identifier for this :term:`job`
+:keyword: A keyword that represents the operation being performed by
the :term:`job`:
PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
+ This :term:`job` will prevent caching of URLs matching the
``assetUrl`` until it is removed (or its Time to Live expires)
-:parameters: A string containing key/value pairs representing parameters
associated with the job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime: The date and time at which the job began, in a non-standard format
+:parameters: A string containing key/value pairs representing parameters
associated with the :term:`job` - currently only uses Time to Live e.g.
``"TTL:48h"``
+:startTime: The date and time at which the :term:`job` began, in a
non-standard format
.. code-block:: http
:caption: Response Example
@@ -108,9 +109,9 @@ Response Structure
``POST``
========
-Creates a new content invalidation job.
+Creates a new :term:`Content Invalidation Job`.
-.. caution:: Creating a content invalidation job immediately triggers a
CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that content invalidation jobs become
active **immediately** at their ``startTime`` - unlike most other configuration
changes they do not wait for a :term:`Snapshot` or a "Queue Updates".
Furthermore, if the global :term:`Par [...]
+.. caution:: Creating a :term:`Content Invalidation Job` immediately triggers
a CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs`
become active **immediately** at their ``startTime`` - unlike most other
configuration changes they do not wait for a :term:`Snapshot` or a "Queue
Updates". Furthermore, if the g [...]
:Auth. Required: Yes
:Roles Required: "operations" or "admin"\ [#tenancy]_
@@ -121,7 +122,7 @@ Request Structure
:deliveryService: This should either be the integral, unique identifier of a
:term:`Delivery Service`, or a string containing an :ref:`ds-xmlid`
:startTime: This can be a string in the legacy ``YYYY-MM-DD HH:MM:SS`` format,
or a string in :rfc:`3339` format, or a string representing a date in the same
non-standard format as the ``last_updated`` fields common in other API
responses, or finally it can be a number indicating the number of milliseconds
since the Unix Epoch (January 1, 1970 UTC). This date must be in the future.
:regex: A regular expression that will be used to match the path part of URIs
for content stored on :term:`cache servers` that service traffic for the
:term:`Delivery Service` identified by ``deliveryService``.
-:ttl: Either the number of hours for which the content invalidation job should
remain active, or a "duration" string, which is a sequence of numbers followed
by units. The accepted units are:
+:ttl: Either the number of hours for which the :term:`Content Invalidation
Job` should remain active, or a "duration" string, which is a sequence of
numbers followed by units. The accepted units are:
- ``h`` gives a duration in hours
- ``m`` gives a duration in minutes
@@ -155,16 +156,16 @@ Request Structure
Response Structure
------------------
:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-:createdBy: The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates
-:id: An integral, unique identifier for this job
-:keyword: A keyword that represents the operation being performed by
the job:
+:createdBy: The username of the user who initiated the :term:`job`
+:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this :term:`job` operates
+:id: An integral, unique identifier for this :term:`job`
+:keyword: A keyword that represents the operation being performed by
the :term:`job`:
PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
+ This :term:`job` will prevent caching of URLs matching the
``assetUrl`` until it is removed (or its Time to Live expires)
-:parameters: A string containing key/value pairs representing parameters
associated with the job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime: The date and time at which the job began, in a non-standard format
+:parameters: A string containing key/value pairs representing parameters
associated with the :term:`job` - currently only uses Time to Live e.g.
``"TTL:48h"``
+:startTime: The date and time at which the :term:`job` began, in a
non-standard format
.. code-block:: http
:caption: Response Example
@@ -204,9 +205,9 @@ Response Structure
``PUT``
=======
-Replaces an existing content invalidation job with a new one provided in the
request. This method of editing a content invalidation job does not prevent the
requesting user from changing fields that normally only have one value. Use
with care.
+Replaces an existing :term:`Content Invalidation Job` with a new one provided
in the request. This method of editing a :term:`Content Invalidation Job` does
not prevent the requesting user from changing fields that normally only have
one value. Use with care.
-.. caution:: Modifying a content invalidation job immediately triggers a
CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that content invalidation jobs become
active **immediately** at their ``startTime`` - unlike most other configuration
changes they do not wait for a :term:`Snapshot` or a "Queue Updates".
Furthermore, if the global :term:`Pa [...]
+.. caution:: Modifying a :term:`Content Invalidation Job` immediately triggers
a CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs`
become active **immediately** at their ``startTime`` - unlike most other
configuration changes they do not wait for a :term:`Snapshot` or a "Queue
Updates". Furthermore, if the [...]
:Auth. Required: Yes
:Roles Required: "operations" or "admin"\ [#tenancy]_
@@ -216,25 +217,25 @@ Request Structure
-----------------
.. table:: Query Parameters
-
+------+----------+--------------------------------------------------------------------------------+
- | Name | Required | Description
|
-
+======+==========+================================================================================+
- | id | yes | The integral, unique identifier of the content
invalidation job being modified |
-
+------+----------+--------------------------------------------------------------------------------+
+
+------+----------+----------------------------------------------------------------------------------------+
+ | Name | Required | Description
|
+
+======+==========+========================================================================================+
+ | id | yes | The integral, unique identifier of the
:term:`Content Invalidation Job` being modified |
+
+------+----------+----------------------------------------------------------------------------------------+
:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
.. note:: Unlike in the payloads of POST_ requests to this endpoint,
this must be a **full** URL regular expression, as it is **not** combined with
the :ref:`ds-origin-url` of the :term:`Delivery Service` identified by
``deliveryService``.
-:createdBy: The username of the user who initiated the job\ [#readonly]_
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates\ [#readonly]_ - unlike POST_ request payloads, this cannot be
an integral, unique identifier
-:id: An integral, unique identifier for this job\ [#readonly]_
-:keyword: A keyword that represents the operation being performed by
the job. It can have any (string) value, but the only value with any meaning to
Traffic Control is:
+:createdBy: The username of the user who initiated the :term:`job`\
[#readonly]_
+:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this :term:`job` operates\ [#readonly]_ - unlike POST_ request payloads, this
cannot be an integral, unique identifier
+:id: An integral, unique identifier for this :term:`job`\
[#readonly]_
+:keyword: A keyword that represents the operation being performed by
the :term:`job`. It can have any (string) value, but the only value with any
meaning to Traffic Control is:
PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
+ This :term:`job` will prevent caching of URLs matching the
``assetUrl`` until it is removed (or its Time to Live expires)
-:parameters: A string containing space-separated key/value pairs - delimited
by colons (:kbd:`:`\ s) representing parameters associated with the job. In
practice, any string can be passed as a job's ``parameters``, but the only
value with meaning is a single key/value pair indicated a :abbr:`TTL (Time To
Live)` in hours in the format :file:`TTL:{hours}h`, and any other type of value
may cause components of Traffic Control to work improperly or not at all.
+:parameters: A string containing space-separated key/value pairs - delimited
by colons (:kbd:`:`\ s) representing parameters associated with the
:term:`job`. In practice, any string can be passed as a :term:`job`'s
``parameters``, but the only value with meaning is a single key/value pair
indicated a :abbr:`TTL (Time To Live)` in hours in the format
:file:`TTL:{hours}h`, and any other type of value may cause components of
Traffic Control to work improperly or not at all.
:startTime: This can be a string in the legacy ``YYYY-MM-DD HH:MM:SS``
format, or a string in :rfc:`3339` format, or a string representing a date in
the same non-standard format as the ``last_updated`` fields common in other API
responses, or finally it can be a number indicating the number of milliseconds
since the Unix Epoch (January 1, 1970 UTC). This **must** be in the future, but
only by no more than two days.
.. code-block:: http
@@ -263,16 +264,16 @@ Request Structure
Response Structure
------------------
:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-:createdBy: The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates
-:id: An integral, unique identifier for this job
-:keyword: A keyword that represents the operation being performed by
the job:
+:createdBy: The username of the user who initiated the :term:`job`
+:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this :term:`job` operates
+:id: An integral, unique identifier for this :term:`job`
+:keyword: A keyword that represents the operation being performed by
the :term:`job`:
PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
+ This :term:`job` will prevent caching of URLs matching the
``assetUrl`` until it is removed (or its Time to Live expires)
-:parameters: A string containing key/value pairs representing parameters
associated with the job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime: The date and time at which the job began, in a non-standard format
+:parameters: A string containing key/value pairs representing parameters
associated with the :term:`job` - currently only uses Time to Live e.g.
``"TTL:48h"``
+:startTime: The date and time at which the :term:`job` began, in a
non-standard format
.. code-block:: http
:caption: Response Example
@@ -291,7 +292,7 @@ Response Structure
Content-Length: 234
{ "alerts": [{
- "text": "Content invalidation job updated",
+ "text": "job updated",
"level": "success"
}],
"response": {
@@ -307,11 +308,11 @@ Response Structure
``DELETE``
==========
-Deletes a content invalidation job.
+Deletes a :term:`Content Invalidation Job`.
-.. tip:: Content invalidation jobs that have passed their :abbr:`TTL (Time To
Live)` are not automatically deleted - for record-keeping purposes - so use
this to clean up old jobs that are no longer useful.
+.. tip:: :term:`Content Invalidation Jobs` that have passed their :abbr:`TTL
(Time To Live)` are not automatically deleted - for record-keeping purposes -
so use this to clean up old :term:`jobs` that are no longer useful.
-.. caution:: Deleting a content invalidation job immediately triggers a
CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that content invalidation jobs become
active **immediately** at their ``startTime`` - unlike most other configuration
changes they do not wait for a :term:`Snapshot` or a "Queue Updates".
Furthermore, if the global :term:`Par [...]
+.. caution:: Deleting a :term:`Content Invalidation Job` immediately triggers
a CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs`
become active **immediately** at their ``startTime`` - unlike most other
configuration changes they do not wait for a :term:`Snapshot` or a "Queue
Updates". Furthermore, if the g [...]
:Auth. Required: Yes
:Roles Required: "operations" or "admin"\ [#tenancy]_
@@ -321,11 +322,11 @@ Request Structure
-----------------
.. table:: Query Parameters
-
+------+----------+--------------------------------------------------------------------------------+
- | Name | Required | Description
|
-
+======+==========+================================================================================+
- | id | yes | The integral, unique identifier of the content
invalidation job being modified |
-
+------+----------+--------------------------------------------------------------------------------+
+
+------+----------+----------------------------------------------------------------------------------------+
+ | Name | Required | Description
|
+
+======+==========+========================================================================================+
+ | id | yes | The integral, unique identifier of the
:term:`Content Invalidation Job` being modified |
+
+------+----------+----------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
@@ -342,16 +343,16 @@ Request Structure
Response Structure
------------------
:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-:createdBy: The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates
-:id: An integral, unique identifier for this job
-:keyword: A keyword that represents the operation being performed by
the job:
+:createdBy: The username of the user who initiated the :term:`job`
+:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this :term:`job` operates
+:id: An integral, unique identifier for this :term:`job`
+:keyword: A keyword that represents the operation being performed by
the :term:`job`:
PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
+ This :term:`job` will prevent caching of URLs matching the
``assetUrl`` until it is removed (or its Time to Live expires)
-:parameters: A string containing key/value pairs representing parameters
associated with the job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime: The date and time at which the job began, in a non-standard format
+:parameters: A string containing key/value pairs representing parameters
associated with the :term:`job` - currently only uses Time to Live e.g.
``"TTL:48h"``
+:startTime: The date and time at which the :term:`job` began, in a
non-standard format
.. code-block:: http
:caption: Response Example
@@ -371,7 +372,7 @@ Response Structure
{ "alerts": [
{
- "text": "Content invalidation job was deleted",
+ "text": "job was deleted",
"level": "success"
}
],
@@ -386,5 +387,5 @@ Response Structure
}}
-.. [#tenancy] When viewing content invalidation jobs, only those jobs that
operate on a :term:`Delivery Service` visible to the requesting user's
:term:`Tenant` will be returned. Likewise, creating a new content invalidation
job requires that the target :term:`Delivery Service` is modifiable by the
requesting user's :term:`Tenant`. However, when modifying or deleting an
existing content invalidation job, the operation can be completed if and only
if the requesting user's :term:`Tenant` i [...]
-.. [#readonly] This field must exist, but it must *not* be different than the
same field of the existing job (i.e. as seen in a GET_ response)
+.. [#tenancy] When viewing :term:`Content Invalidation Jobs`, only those jobs
that operate on a :term:`Delivery Service` visible to the requesting user's
:term:`Tenant` will be returned. Likewise, creating a new :term:`Content
Invalidation Jobs` requires that the target :term:`Delivery Service` is
modifiable by the requesting user's :term:`Tenant`. However, when modifying or
deleting an existing :term:`Content Invalidation Jobs`, the operation can be
completed if and only if the requesti [...]
+.. [#readonly] This field must exist, but it must *not* be different than the
same field of the existing :term:`job` (i.e. as seen in a GET_ response)
diff --git a/docs/source/api/v2/servers_hostname_update_status.rst
b/docs/source/api/v2/servers_hostname_update_status.rst
index 8324298..ea08b17 100644
--- a/docs/source/api/v2/servers_hostname_update_status.rst
+++ b/docs/source/api/v2/servers_hostname_update_status.rst
@@ -23,7 +23,7 @@
``GET``
=======
-Retrieves information regarding pending updates and revalidation jobs for a
given server
+Retrieves information regarding pending updates and :term:`Content
Invalidation Jobs` for a given server
:Auth. Required: Yes
:Roles Required: None
@@ -55,14 +55,14 @@ Each object in the returned array\ [1]_ will contain the
following fields:
:host_id: The integral, unique identifier for the server for
which the other fields in this object represent the pending updates and
revalidation status
:host_name: The (short) hostname of the server for which the other
fields in this object represent the pending updates and revalidation status
:parent_pending: A boolean telling whether or not the :term:`parents` of
this server have pending updates
-:parent_reval_pending: A boolean telling whether or not the :term:`parents` of
this server have pending revalidation jobs
-:reval_pending: ``true`` if the server has pending revalidation jobs,
``false`` otherwise
+:parent_reval_pending: A boolean telling whether or not the :term:`parents` of
this server have pending :term:`Content Invalidation Jobs`
+:reval_pending: ``true`` if the server has pending :term:`Content
Invalidation Jobs`, ``false`` otherwise
:status: The name of the status of this server
.. seealso:: :ref:`health-proto` gives more information on how these
statuses are used, and the ``GET`` method of the :ref:`to-api-statuses`
endpoint can be used to retrieve information about all server statuses
configured in Traffic Ops.
:upd_pending: ``true`` if the server has pending updates, ``false``
otherwise
-:use_reval_pending: A boolean which tells :term:`ORT` whether or not this
version of Traffic Ops should use pending revalidation jobs
+:use_reval_pending: A boolean which tells :term:`ORT` whether or not this
version of Traffic Ops should use pending :term:`Content Invalidation Jobs`
.. note:: This field was introduced to give :term:`ORT` the ability to
work with Traffic Control versions 1.x and 2.x seamlessly - as of Traffic
Control v3.0 there is no reason for this field to ever be ``false``.
diff --git a/docs/source/api/v3/deliveryservices_request.rst
b/docs/source/api/v3/deliveryservices_request.rst
index d00bac1..f0f1a7d 100644
--- a/docs/source/api/v3/deliveryservices_request.rst
+++ b/docs/source/api/v3/deliveryservices_request.rst
@@ -36,7 +36,7 @@ Request Structure
-----------------
:details: An object describing the actual parameters for the Delivery Service
request
- :customer: Name of the customer associated with the :term:`Delivery
Service` - must only contain alphanumeric characters and the characters
:kbd:`@`, :kbd:`!`, :kbd:`#`, :kbd:`$`, :kbd:`%`, :kbd:`^`, :kbd:`&`, :kbd:`*`,
:kbd:`(`, :kbd:`)`, :kbd:`[`, :kbd:`]`, :kbd:`.`, :kbd:` `, and :kbd:`-`
+ :customer: Name of the customer associated with the :term:`Delivery
Service` - must only contain alphanumeric characters and the characters
:kbd:`@`, :kbd:`!`, :kbd:`#`, :kbd:`$`, :kbd:`%`, :kbd:`^`, :kbd:`&`, :kbd:`*`,
:kbd:`(`, :kbd:`)`, :kbd:`[`, :kbd:`]`, :kbd:`.`, :kbd:`\ `, and :kbd:`-`
.. versionchanged:: ATCv6
Prior to ATC version 6, this field had no restrictions.
diff --git a/docs/source/api/v3/jobs.rst b/docs/source/api/v3/jobs.rst
index f5e7b02..46cafaa 100644
--- a/docs/source/api/v3/jobs.rst
+++ b/docs/source/api/v3/jobs.rst
@@ -21,7 +21,7 @@
``GET``
=======
-Retrieve content invalidation jobs.
+Retrieve :term:`Content Invalidation Jobs`.
:Auth. Required: Yes
:Roles Required: None\ [#tenancy]_
@@ -34,23 +34,24 @@ Request Structure
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Name | Required | Description
|
+======================+==========+==================================================================================================================================================================+
- | assetUrl | no | Return only invalidation jobs that
operate on URLs by matching this regular expression
|
+ | assetUrl | no | Return only :term:`Content
Invalidation Jobs` that operate on URLs by matching this regular expression
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | cdn | no | Return only invalidation jobs for
delivery services with this CDN name
|
+ | cdn | no | Return only :term:`Content
Invalidation Jobs` for delivery services with this CDN name
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | createdBy | no | Return only invalidation jobs that
were created by the user with this username
|
+ | createdBy | no | Return only :term:`Content
Invalidation Jobs` that were created by the user with this username
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | deliveryService | no | Return only invalidation jobs that
operate on the :term:`Delivery Service` with this :ref:`ds-xmlid`
|
+ | deliveryService | no | Return only :term:`Content
Invalidation Jobs` that operate on the :term:`Delivery Service` with this
:ref:`ds-xmlid` |
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | dsId | no | Return only invalidation jobs
pending on the :term:`Delivery Service` identified by this integral, unique
identifier |
+ | dsId | no | Return only :term:`Content
Invalidation Jobs` pending on the :term:`Delivery Service` identified by this
integral, unique identifier |
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | id | no | Return only the single invalidation
job identified by this integral, unique identifer
|
+ | id | no | Return only the single invalidation
:term:`Content Invalidation Job` identified by this integral, unique identifer
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | keyword | no | Return only invalidation jobs that
have this "keyword" - only "PURGE" should exist
|
+ | keyword | no | Return only :term:`Content
Invalidation Jobs` that have this "keyword" - only "PURGE" should exist
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | maxRevalDurationDays | no | Return only invalidation jobs with
a startTime that is within the window defined by the ``maxRevalDurationDays``
:term:`Parameter` in :ref:`the-global-profile` |
+ | maxRevalDurationDays | no | Return only :term:`Content
Invalidation Jobs` with a startTime that is within the window defined by the
``maxRevalDurationDays`` :term:`Parameter` in |
+ | | | :ref:`the-global-profile`
|
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | userId | no | Return only invalidation jobs
created by the user identified by this integral, unique identifier
|
+ | userId | no | Return only :term:`Content
Invalidation Jobs` created by the user identified by this integral, unique
identifier |
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
@@ -68,16 +69,16 @@ Request Structure
Response Structure
------------------
:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-:createdBy: The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates
-:id: An integral, unique identifier for this job
-:keyword: A keyword that represents the operation being performed by
the job:
+:createdBy: The username of the user who initiated the :term:`Content
Invalidation Job`
+:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this :term:`Content Invalidation Job` operates
+:id: An integral, unique identifier for this :term:`Content
Invalidation Job`
+:keyword: A keyword that represents the operation being performed by
the :term:`Content Invalidation Job`:
PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
+ This :term:`Content Invalidation Job` will prevent caching of
URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires)
-:parameters: A string containing key/value pairs representing parameters
associated with the job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime: The date and time at which the job began, in a non-standard format
+:parameters: A string containing key/value pairs representing parameters
associated with the :term:`Content Invalidation Job` - currently only uses Time
to Live e.g. ``"TTL:48h"``
+:startTime: The date and time at which the :term:`Content Invalidation Job`
began, in a non-standard format
.. code-block:: http
:caption: Response Example
@@ -108,9 +109,9 @@ Response Structure
``POST``
========
-Creates a new content invalidation job.
+Creates a new :term:`Content Invalidation Job`.
-.. caution:: Creating a content invalidation job immediately triggers a
CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that content invalidation jobs become
active **immediately** at their ``startTime`` - unlike most other configuration
changes they do not wait for a :term:`Snapshot` or a "Queue Updates".
Furthermore, if the global :term:`Par [...]
+.. caution:: Creating a :term:`Content Invalidation Job` immediately triggers
a CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs`
become active **immediately** at their ``startTime`` - unlike most other
configuration changes they do not wait for a :term:`Snapshot` or a "Queue
Updates". Furthermore, if the g [...]
:Auth. Required: Yes
:Roles Required: "operations" or "admin"\ [#tenancy]_
@@ -121,7 +122,7 @@ Request Structure
:deliveryService: This should either be the integral, unique identifier of a
:term:`Delivery Service`, or a string containing an :ref:`ds-xmlid`
:startTime: This can be a string in the legacy ``YYYY-MM-DD HH:MM:SS`` format,
or a string in :rfc:`3339` format, or a string representing a date in the same
non-standard format as the ``last_updated`` fields common in other API
responses, or finally it can be a number indicating the number of milliseconds
since the Unix Epoch (January 1, 1970 UTC). This date must be in the future.
:regex: A regular expression that will be used to match the path part of URIs
for content stored on :term:`cache servers` that service traffic for the
:term:`Delivery Service` identified by ``deliveryService``.
-:ttl: Either the number of hours for which the content invalidation job should
remain active, or a "duration" string, which is a sequence of numbers followed
by units. The accepted units are:
+:ttl: Either the number of hours for which the :term:`Content Invalidation
Job` should remain active, or a "duration" string, which is a sequence of
numbers followed by units. The accepted units are:
- ``h`` gives a duration in hours
- ``m`` gives a duration in minutes
@@ -155,16 +156,16 @@ Request Structure
Response Structure
------------------
:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-:createdBy: The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates
-:id: An integral, unique identifier for this job
-:keyword: A keyword that represents the operation being performed by
the job:
+:createdBy: The username of the user who initiated the :term:`Content
Invalidation Job`
+:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this :term:`Content Invalidation Job` operates
+:id: An integral, unique identifier for this :term:`Content
Invalidation Job`
+:keyword: A keyword that represents the operation being performed by
the :term:`Content Invalidation Job`:
PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
+ This :term:`Content Invalidation Job` will prevent caching of
URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires)
-:parameters: A string containing key/value pairs representing parameters
associated with the job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime: The date and time at which the job began, in a non-standard format
+:parameters: A string containing key/value pairs representing parameters
associated with the :term:`Content Invalidation Job` - currently only uses Time
to Live e.g. ``"TTL:48h"``
+:startTime: The date and time at which the :term:`Content Invalidation Job`
began, in a non-standard format
.. code-block:: http
:caption: Response Example
@@ -204,9 +205,9 @@ Response Structure
``PUT``
=======
-Replaces an existing content invalidation job with a new one provided in the
request. This method of editing a content invalidation job does not prevent the
requesting user from changing fields that normally only have one value. Use
with care.
+Replaces an existing :term:`Content Invalidation Job` with a new one provided
in the request. This method of editing a :term:`Content Invalidation Job` does
not prevent the requesting user from changing fields that normally only have
one value. Use with care.
-.. caution:: Modifying a content invalidation job immediately triggers a
CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that content invalidation jobs become
active **immediately** at their ``startTime`` - unlike most other configuration
changes they do not wait for a :term:`Snapshot` or a "Queue Updates".
Furthermore, if the global :term:`Pa [...]
+.. caution:: Modifying a :term:`Content Invalidation Job` immediately triggers
a CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs`
become active **immediately** at their ``startTime`` - unlike most other
configuration changes they do not wait for a :term:`Snapshot` or a "Queue
Updates". Furthermore, if the [...]
:Auth. Required: Yes
:Roles Required: "operations" or "admin"\ [#tenancy]_
@@ -216,25 +217,25 @@ Request Structure
-----------------
.. table:: Query Parameters
-
+------+----------+--------------------------------------------------------------------------------+
- | Name | Required | Description
|
-
+======+==========+================================================================================+
- | id | yes | The integral, unique identifier of the content
invalidation job being modified |
-
+------+----------+--------------------------------------------------------------------------------+
+
+------+----------+----------------------------------------------------------------------------------------+
+ | Name | Required | Description
|
+
+======+==========+========================================================================================+
+ | id | yes | The integral, unique identifier of the
:term:`Content Invalidation Job` being modified |
+
+------+----------+----------------------------------------------------------------------------------------+
:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
.. note:: Unlike in the payloads of POST_ requests to this endpoint,
this must be a **full** URL regular expression, as it is **not** combined with
the :ref:`ds-origin-url` of the :term:`Delivery Service` identified by
``deliveryService``.
-:createdBy: The username of the user who initiated the job\ [#readonly]_
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates\ [#readonly]_ - unlike POST_ request payloads, this cannot be
an integral, unique identifier
-:id: An integral, unique identifier for this job\ [#readonly]_
-:keyword: A keyword that represents the operation being performed by
the job. It can have any (string) value, but the only value with any meaning to
Traffic Control is:
+:createdBy: The username of the user who initiated the :term:`Content
Invalidation Job`\ [#readonly]_
+:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this :term:`Content Invalidation Job` operates\ [#readonly]_ - unlike POST_
request payloads, this cannot be an integral, unique identifier
+:id: An integral, unique identifier for this :term:`Content
Invalidation Job`\ [#readonly]_
+:keyword: A keyword that represents the operation being performed by
the :term:`Content Invalidation Job`. It can have any (string) value, but the
only value with any meaning to Traffic Control is:
PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
+ This :term:`Content Invalidation Job` will prevent caching of
URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires)
-:parameters: A string containing space-separated key/value pairs - delimited
by colons (:kbd:`:`\ s) representing parameters associated with the job. In
practice, any string can be passed as a job's ``parameters``, but the only
value with meaning is a single key/value pair indicated a :abbr:`TTL (Time To
Live)` in hours in the format :file:`TTL:{hours}h`, and any other type of value
may cause components of Traffic Control to work improperly or not at all.
+:parameters: A string containing space-separated key/value pairs - delimited
by colons (:kbd:`:`\ s) representing parameters associated with the
:term:`Content Invalidation Job`. In practice, any string can be passed as a
:term:`Content Invalidation Job`'s ``parameters``, but the only value with
meaning is a single key/value pair indicated a :abbr:`TTL (Time To Live)` in
hours in the format :file:`TTL:{hours}h`, and any other type of value may cause
components of Traffic Control to work [...]
:startTime: This can be a string in the legacy ``YYYY-MM-DD HH:MM:SS``
format, or a string in :rfc:`3339` format, or a string representing a date in
the same non-standard format as the ``last_updated`` fields common in other API
responses, or finally it can be a number indicating the number of milliseconds
since the Unix Epoch (January 1, 1970 UTC). This **must** be in the future, but
only by no more than two days.
.. code-block:: http
@@ -263,16 +264,16 @@ Request Structure
Response Structure
------------------
:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-:createdBy: The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates
-:id: An integral, unique identifier for this job
-:keyword: A keyword that represents the operation being performed by
the job:
+:createdBy: The username of the user who initiated the :term:`Content
Invalidation Job`
+:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this :term:`Content Invalidation Job` operates
+:id: An integral, unique identifier for this :term:`Content
Invalidation Job`
+:keyword: A keyword that represents the operation being performed by
the :term:`Content Invalidation Job`:
PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
+ This :term:`Content Invalidation Job` will prevent caching of
URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires)
-:parameters: A string containing key/value pairs representing parameters
associated with the job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime: The date and time at which the job began, in a non-standard format
+:parameters: A string containing key/value pairs representing parameters
associated with the :term:`Content Invalidation Job` - currently only uses Time
to Live e.g. ``"TTL:48h"``
+:startTime: The date and time at which the :term:`Content Invalidation Job`
began, in a non-standard format
.. code-block:: http
:caption: Response Example
@@ -307,11 +308,11 @@ Response Structure
``DELETE``
==========
-Deletes a content invalidation job.
+Deletes a :term:`Content Invalidation Job`.
-.. tip:: Content invalidation jobs that have passed their :abbr:`TTL (Time To
Live)` are not automatically deleted - for record-keeping purposes - so use
this to clean up old jobs that are no longer useful.
+.. tip:: Content :term:`Content Invalidation Jobs` that have passed their
:abbr:`TTL (Time To Live)` are not automatically deleted - for record-keeping
purposes - so use this to clean up old :term:`jobs` that are no longer useful.
-.. caution:: Deleting a content invalidation job immediately triggers a
CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that content invalidation jobs become
active **immediately** at their ``startTime`` - unlike most other configuration
changes they do not wait for a :term:`Snapshot` or a "Queue Updates".
Furthermore, if the global :term:`Par [...]
+.. caution:: Deleting a :term:`Content Invalidation Job` immediately triggers
a CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs`
become active **immediately** at their ``startTime`` - unlike most other
configuration changes they do not wait for a :term:`Snapshot` or a "Queue
Updates". Furthermore, if the g [...]
:Auth. Required: Yes
:Roles Required: "operations" or "admin"\ [#tenancy]_
@@ -321,11 +322,11 @@ Request Structure
-----------------
.. table:: Query Parameters
-
+------+----------+--------------------------------------------------------------------------------+
- | Name | Required | Description
|
-
+======+==========+================================================================================+
- | id | yes | The integral, unique identifier of the content
invalidation job being modified |
-
+------+----------+--------------------------------------------------------------------------------+
+
+------+----------+----------------------------------------------------------------------------------------+
+ | Name | Required | Description
|
+
+======+==========+========================================================================================+
+ | id | yes | The integral, unique identifier of the
:term:`Content Invalidation Job` being modified |
+
+------+----------+----------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
@@ -342,16 +343,16 @@ Request Structure
Response Structure
------------------
:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-:createdBy: The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates
-:id: An integral, unique identifier for this job
-:keyword: A keyword that represents the operation being performed by
the job:
+:createdBy: The username of the user who initiated the :term:`Content
Invalidation Job`
+:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this :term:`Content Invalidation Job` operates
+:id: An integral, unique identifier for this :term:`Content
Invalidation Job`
+:keyword: A keyword that represents the operation being performed by
the :term:`Content Invalidation Job`:
PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
+ This :term:`Content Invalidation Job` will prevent caching of
URLs matching the ``assetUrl`` until it is removed (or its Time to Live expires)
-:parameters: A string containing key/value pairs representing parameters
associated with the job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime: The date and time at which the job began, in a non-standard format
+:parameters: A string containing key/value pairs representing parameters
associated with the :term:`Content Invalidation Job` - currently only uses Time
to Live e.g. ``"TTL:48h"``
+:startTime: The date and time at which the :term:`Content Invalidation Job`
began, in a non-standard format
.. code-block:: http
:caption: Response Example
@@ -386,5 +387,5 @@ Response Structure
}}
-.. [#tenancy] When viewing content invalidation jobs, only those jobs that
operate on a :term:`Delivery Service` visible to the requesting user's
:term:`Tenant` will be returned. Likewise, creating a new content invalidation
job requires that the target :term:`Delivery Service` is modifiable by the
requesting user's :term:`Tenant`. However, when modifying or deleting an
existing content invalidation job, the operation can be completed if and only
if the requesting user's :term:`Tenant` i [...]
-.. [#readonly] This field must exist, but it must *not* be different than the
same field of the existing job (i.e. as seen in a GET_ response)
+.. [#tenancy] When viewing :term:`Content Invalidation Jobs`, only those
:term:`jobs` that operate on a :term:`Delivery Service` visible to the
requesting user's :term:`Tenant` will be returned. Likewise, creating a new
:term:`Content Invalidation Jobs` requires that the target :term:`Delivery
Service` is modifiable by the requesting user's :term:`Tenant`. However, when
modifying or deleting an existing :term:`Content Invalidation Jobs`, the
operation can be completed if and only if the [...]
+.. [#readonly] This field must exist, but it must *not* be different than the
same field of the existing :term:`Content Invalidation Job` (i.e. as seen in a
GET_ response)
diff --git a/docs/source/api/v3/servers_hostname_update_status.rst
b/docs/source/api/v3/servers_hostname_update_status.rst
index 3429cc9..8ef5755 100644
--- a/docs/source/api/v3/servers_hostname_update_status.rst
+++ b/docs/source/api/v3/servers_hostname_update_status.rst
@@ -23,7 +23,7 @@
``GET``
=======
-Retrieves information regarding pending updates and revalidation jobs for a
given server
+Retrieves information regarding pending updates and :term:`Content
Invalidation Jobs` for a given server
:Auth. Required: Yes
:Roles Required: None
@@ -55,14 +55,14 @@ Each object in the returned array\ [1]_ will contain the
following fields:
:host_id: The integral, unique identifier for the server for
which the other fields in this object represent the pending updates and
revalidation status
:host_name: The (short) hostname of the server for which the other
fields in this object represent the pending updates and revalidation status
:parent_pending: A boolean telling whether or not any :term:`Topology`
ancestor or :term:`parent` of this server has pending updates
-:parent_reval_pending: A boolean telling whether or not any :term:`Topology`
ancestor or :term:`parent` of this server has pending revalidation jobs
-:reval_pending: ``true`` if the server has pending revalidation jobs,
``false`` otherwise
+:parent_reval_pending: A boolean telling whether or not any :term:`Topology`
ancestor or :term:`parent` of this server has pending :term:`Content
Invalidation Jobs`
+:reval_pending: ``true`` if the server has pending :term:`Content
Invalidation Jobs`, ``false`` otherwise
:status: The name of the status of this server
.. seealso:: :ref:`health-proto` gives more information on how these
statuses are used, and the ``GET`` method of the :ref:`to-api-v3-statuses`
endpoint can be used to retrieve information about all server statuses
configured in Traffic Ops.
:upd_pending: ``true`` if the server has pending updates, ``false``
otherwise
-:use_reval_pending: A boolean which tells :term:`ORT` whether or not this
version of Traffic Ops should use pending revalidation jobs
+:use_reval_pending: A boolean which tells :term:`ORT` whether or not this
version of Traffic Ops should use pending :term:`Content Invalidation Jobs`
.. note:: This field was introduced to give :term:`ORT` the ability to
work with Traffic Control versions 1.x and 2.x seamlessly - as of Traffic
Control v3.0 there is no reason for this field to ever be ``false``.
diff --git a/docs/source/api/v4/jobs.rst b/docs/source/api/v4/jobs.rst
index ed9f822..ed1eaee 100644
--- a/docs/source/api/v4/jobs.rst
+++ b/docs/source/api/v4/jobs.rst
@@ -21,44 +21,43 @@
``GET``
=======
-Retrieve content invalidation jobs.
+Retrieve :term:`Content Invalidation Jobs`.
-:Auth. Required: Yes
-:Roles Required: None\ [#tenancy]_
-:Permissions Required: JOB:READ, DELIVERY-SERVICE:READ
-:Response Type: Array
+:Auth. Required: Yes
+:Roles Required: None\ [#tenancy]_
+:Permissions Required: JOB:READ, DELIVERY-SERVICE:READ\ [#tenancy]_
+:Response Type: Array
Request Structure
-----------------
.. table:: Request Query Parameters
-
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | Name | Required | Description
|
-
+======================+==========+==================================================================================================================================================================+
- | assetUrl | no | Return only invalidation jobs that
operate on URLs by matching this regular expression
|
-
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | cdn | no | Return only invalidation jobs for
delivery services with this CDN name
|
-
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | createdBy | no | Return only invalidation jobs that
were created by the user with this username
|
-
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | deliveryService | no | Return only invalidation jobs that
operate on the :term:`Delivery Service` with this :ref:`ds-xmlid`
|
-
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | dsId | no | Return only invalidation jobs
pending on the :term:`Delivery Service` identified by this integral, unique
identifier |
-
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | id | no | Return only the single invalidation
job identified by this integral, unique identifer
|
-
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | keyword | no | Return only invalidation jobs that
have this "keyword" - only "PURGE" should exist
|
-
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | maxRevalDurationDays | no | Return only invalidation jobs with
a startTime that is within the window defined by the ``maxRevalDurationDays``
:term:`Parameter` in :ref:`the-global-profile` |
-
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
- | userId | no | Return only invalidation jobs
created by the user identified by this integral, unique identifier
|
-
+----------------------+----------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | Name | Required | Description
|
+
+======================+==========+======================================================================================================================================+
+ | assetUrl | no | Return only :term:`Content
Invalidation Jobs` with this :ref:`job-asset-url`
|
+
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | cdn | no | Return only :term:`Content
Invalidation Jobs` for :term:`Delivery Services` within the CDN with this name
|
+
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | createdBy | no | Return only :term:`Content
Invalidation Jobs` that were created by the user with this username
|
+
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | deliveryService | no | Return only :term:`Content
Invalidation Jobs` that operate on the :term:`Delivery Service` with this
:ref:`ds-xmlid` |
+
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | dsId | no | Return only :term:`Content
Invalidation Jobs` pending on the :term:`Delivery Service` identified by this
integral, unique identifier |
+
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | id | no | Return only the single
:term:`Content Invalidation Job` with this :ref:`job-id`
|
+
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | maxRevalDurationDays | no | Return only :term:`Content
Invalidation Jobs` with a :ref:`job-start-time` that is within the window
defined by the |
+ | | | ``maxRevalDurationDays``
:term:`Parameter` in :ref:`the-global-profile`
|
+
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
+ | userId | no | Return only :term:`Content
Invalidation Jobs` created by the user identified by this integral, unique
identifier |
+
+----------------------+----------+--------------------------------------------------------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
- GET /api/4.0/jobs?id=3&dsId=1&userId=2 HTTP/1.1
+ GET /api/4.0/jobs?id=1&dsId=1&userId=2 HTTP/1.1
Host: trafficops.infra.ciab.test
User-Agent: python-requests/2.20.1
Accept-Encoding: gzip, deflate
@@ -84,294 +83,259 @@ Response Structure
:caption: Response Example
HTTP/1.1 200 OK
- Access-Control-Allow-Credentials: true
- Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type,
Accept, Set-Cookie, Cookie
- Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
- Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
- Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54
GMT; Max-Age=3600; HttpOnly
- Whole-Content-Sha512:
gH41oEi2zrd3y8yo+wfohn4/oHU098RpyPnqBzU7HlLUDkMOPKjAZnamcYqfdy7yDCFDUcgqkvbFAvnljxyb8w==
+ Permissions-Policy: interest-cohort=()
+ Set-Cookie: mojolicious=...
+ Vary: Accept-Encoding
X-Server-Name: traffic_ops_golang/
- Date: Tue, 18 Jun 2019 19:47:30 GMT
- Content-Length: 186
+ Date: Fri, 12 Nov 2021 19:30:36 GMT
+ Content-Length: 206
{ "response": [{
- "assetUrl": "http://origin.infra.ciab.test/.*";,
+ "id": 1,
+ "assetUrl": "http://origin.infra.ciab.test/.+";,
"createdBy": "admin",
"deliveryService": "demo1",
- "id": 3,
- "keyword": "PURGE",
- "parameters": "TTL:2h",
- "startTime": "2019-06-18 21:28:31+00"
+ "ttlHours": 72,
+ "invalidationType": "REFETCH",
+ "startTime": "2021-11-09T01:02:03Z"
}]}
+
``POST``
========
-Creates a new content invalidation job.
+Creates a new :term:`Content Invalidation Jobs`.
-.. caution:: Creating a content invalidation job immediately triggers a
CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that content invalidation jobs become
active **immediately** at their ``startTime`` - unlike most other configuration
changes they do not wait for a :term:`Snapshot` or a "Queue Updates".
Furthermore, if the global :term:`Par [...]
+.. caution:: Creating a :term:`Content Invalidation Job` immediately triggers
a CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs`
become active **immediately** at their ``startTime`` - unlike most other
configuration changes they do not wait for a :term:`Snapshot` or a "Queue
Updates". Furthermore, if the g [...]
-:Auth. Required: Yes
-:Roles Required: "operations" or "admin"\ [#tenancy]_
-:Permissions Required: JOB:CREATE, JOB:READ, DELIVERY-SERVICE:READ,
DELIVERY-SERVICE:UPDATE
-:Response Type: Object
+:Auth. Required: Yes
+:Roles Required: "operations" or "admin"\ [#tenancy]_
+:Permissions Required: JOB:CREATE, JOB:READ, DELIVERY-SERVICE:READ,
DELIVERY-SERVICE:UPDATE\ [#tenancy]_
+:Response Type: Object
Request Structure
-----------------
-:deliveryService: This should either be the integral, unique identifier of a
:term:`Delivery Service`, or a string containing an :ref:`ds-xmlid`
-:startTime: This can be a string in the legacy ``YYYY-MM-DD HH:MM:SS`` format,
or a string in :rfc:`3339` format, or a string representing a date in the same
non-standard format as the ``last_updated`` fields common in other API
responses, or finally it can be a number indicating the number of milliseconds
since the Unix Epoch (January 1, 1970 UTC). This date must be in the future.
-:regex: A regular expression that will be used to match the path part of URIs
for content stored on :term:`cache servers` that service traffic for the
:term:`Delivery Service` identified by ``deliveryService``.
-:ttl: Either the number of hours for which the content invalidation job should
remain active, or a "duration" string, which is a sequence of numbers followed
by units. The accepted units are:
-
- - ``h`` gives a duration in hours
- - ``m`` gives a duration in minutes
- - ``s`` gives a duration in seconds
- - ``ms`` gives a duration in milliseconds
- - ``us`` (or ``µs``) gives a duration in microseconds
- - ``ns`` gives a duration in nanoseconds
-
- These durations can be combined e.g. ``2h45m`` specifies a TTL of two
hours and forty-five minutes - however note that durations are always rounded
up to the nearest hour so that e.g. ``121m`` becomes three hours. TTLs cannot
ever be negative, obviously.
+:deliveryService: The :ref:`job-ds`
+:invalidationType: The :ref:`job-invalidation-type`
+:regex: The :ref:`job-regex`
+:startTime: The :ref:`job-start-time`
+:ttl: The :ref:`job-ttl`
.. code-block:: http
:caption: Request Example
POST /api/4.0/jobs HTTP/1.1
- Host: trafficops.infra.ciab.test
- User-Agent: python-requests/2.20.1
+ User-Agent: python-requests/2.25.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
- Content-Length: 80
+ Transfer-Encoding: chunked
Content-Type: application/json
{
"deliveryService": "demo1",
- "startTime": 1560893311219,
- "regex": "/.*",
- "ttl": "121m"
+ "invalidationType": "REFRESH",
+ "regex": "/.+",
+ "startTime": "2021-11-09T01:02:03Z",
+ "ttlHours": 72
}
+
Response Structure
------------------
-:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-:createdBy: The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates
-:id: An integral, unique identifier for this job
-:keyword: A keyword that represents the operation being performed by
the job:
-
- PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
-
-:parameters: A string containing key/value pairs representing parameters
associated with the job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime: The date and time at which the job began, in a non-standard format
+:assetUrl: The :ref:`job-asset-url`
+:createdBy: The :ref:`job-created-by`
+:deliveryService: The :ref:`job-ds`
+:id: The :ref:`job-id`.
+:invalidationType: The :ref:`job-invalidation-type`
+:ttlHours: The :ref:`job-ttl`
+:startTime: The :ref:`job-start-time`
.. code-block:: http
:caption: Response Example
HTTP/1.1 200 OK
- Access-Control-Allow-Credentials: true
- Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type,
Accept, Set-Cookie, Cookie
- Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
- Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
- Location: https://trafficops.infra.ciab.test/api/4.0/jobs?id=3
- Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54
GMT; Max-Age=3600; HttpOnly
- Whole-Content-Sha512:
nB2xg2IqO56rLT8dI4+KZgxOsTe5ShctG1U8epRsY9NyyMIpx8TZYt5MrO2QikuYh+NnyoR6V0VICCnGCKZpKw==
+ Location: https://localhost:6443/api/4.0/jobs?id=1
+ Permissions-Policy: interest-cohort=()
+ Set-Cookie: mojolicious=...
+ Vary: Accept-Encoding
X-Server-Name: traffic_ops_golang/
- Date: Tue, 18 Jun 2019 19:37:06 GMT
- Content-Length: 238
+ Date: Mon, 08 Nov 2021 15:44:46 GMT
+ Content-Length: 265
{
"alerts": [
{
- "text": "Invalidation Job creation was
successful",
+ "text": "Invalidation (REFRESH) request created
for http://origin.infra.ciab.test/.+, start:2021-11-09 01:02:03 +0000 UTC end
2021-11-12 01:02:03 +0000 UTC",
"level": "success"
}
],
"response": {
- "assetUrl": "http://origin.infra.ciab.test/.*";,
+ "id": 1,
+ "assetUrl": "http://origin.infra.ciab.test/.+";,
"createdBy": "admin",
"deliveryService": "demo1",
- "id": 3,
- "keyword": "PURGE",
- "parameters": "TTL:2h",
- "startTime": "2019-06-18 21:28:31+00"
+ "ttlHours": 72,
+ "invalidationType": "REFRESH",
+ "startTime": "2021-11-09T01:02:03Z"
}
}
+
``PUT``
=======
-Replaces an existing content invalidation job with a new one provided in the
request. This method of editing a content invalidation job does not prevent the
requesting user from changing fields that normally only have one value. Use
with care.
+Replaces an existing :term:`Content Invalidation Job` with a new one provided
in the request. This method of editing a :term:`Content Invalidation Job` does
not prevent the requesting user from changing fields that normally only have
one value. Use with care.
-.. caution:: Modifying a content invalidation job immediately triggers a
CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that content invalidation jobs become
active **immediately** at their ``startTime`` - unlike most other configuration
changes they do not wait for a :term:`Snapshot` or a "Queue Updates".
Furthermore, if the global :term:`Pa [...]
+.. caution:: Modifying a :term:`Content Invalidation Job` immediately triggers
a CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs`
become active **immediately** at their ``startTime`` - unlike most other
configuration changes they do not wait for a :term:`Snapshot` or a "Queue
Updates". Furthermore, if the [...]
-:Auth. Required: Yes
-:Roles Required: "operations" or "admin"\ [#tenancy]_
-:Permissions Required: JOB:UPDATE, DELIVERY-SERVICE:UPDATE, JOB:READ,
DELIVERY-SERVICE:READ
-:Response Type: Object
+:Auth. Required: Yes
+:Roles Required: "operations" or "admin"\ [#tenancy]_
+:Permissions Required: JOB:UPDATE, DELIVERY-SERVICE:UPDATE, JOB:READ,
DELIVERY-SERVICE:READ\ [#tenancy]_
+:Response Type: Object
Request Structure
-----------------
.. table:: Query Parameters
-
+------+----------+--------------------------------------------------------------------------------+
- | Name | Required | Description
|
-
+======+==========+================================================================================+
- | id | yes | The integral, unique identifier of the content
invalidation job being modified |
-
+------+----------+--------------------------------------------------------------------------------+
-
-:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-
- .. note:: Unlike in the payloads of POST_ requests to this endpoint,
this must be a **full** URL regular expression, as it is **not** combined with
the :ref:`ds-origin-url` of the :term:`Delivery Service` identified by
``deliveryService``.
-
-:createdBy: The username of the user who initiated the job\ [#readonly]_
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates\ [#readonly]_ - unlike POST_ request payloads, this cannot be
an integral, unique identifier
-:id: An integral, unique identifier for this job\ [#readonly]_
-:keyword: A keyword that represents the operation being performed by
the job. It can have any (string) value, but the only value with any meaning to
Traffic Control is:
-
- PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
+
+------+----------+----------------------------------------------------------------------------------------+
+ | Name | Required | Description
|
+
+======+==========+========================================================================================+
+ | id | yes | The integral, unique identifier of the
:term:`Content Invalidation Job` being modified |
+
+------+----------+----------------------------------------------------------------------------------------+
-:parameters: A string containing space-separated key/value pairs - delimited
by colons (:kbd:`:`\ s) representing parameters associated with the job. In
practice, any string can be passed as a job's ``parameters``, but the only
value with meaning is a single key/value pair indicated a :abbr:`TTL (Time To
Live)` in hours in the format :file:`TTL:{hours}h`, and any other type of value
may cause components of Traffic Control to work improperly or not at all.
-:startTime: This can be a string in the legacy ``YYYY-MM-DD HH:MM:SS``
format, or a string in :rfc:`3339` format, or a string representing a date in
the same non-standard format as the ``last_updated`` fields common in other API
responses, or finally it can be a number indicating the number of milliseconds
since the Unix Epoch (January 1, 1970 UTC). This **must** be in the future, but
only by no more than two days.
+:assetUrl: The :ref:`job-asset-url` - the scheme and authority parts
of the regular expression cannot be changed
+:createdBy: The :ref:`job-created-by`\ [#immutable]_
+:deliveryService: The :ref:`job-ds`\ [#immutable]_
+:id: The :ref:`job-id`\ [#immutable]_
+:invalidationType: The :ref:`job-invalidation-type`
+:ttlHours: The :ref:`job-ttl`
+:startTime: The :ref:`job-start-time`
.. code-block:: http
:caption: Request Example
- PUT /api/4.0/jobs?id=3 HTTP/1.1
- Host: trafficops.infra.ciab.test
- User-Agent: python-requests/2.20.1
+ PUT /api/4.0/jobs?id=1 HTTP/1.1
+ User-Agent: python-requests/2.25.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
- Content-Length: 188
- Content-Type: application/json
+ Content-Length: 191
{
- "assetUrl": "http://origin.infra.ciab.test/.*";,
+ "assetUrl": "http://origin.infra.ciab.test/.+";,
"createdBy": "admin",
"deliveryService": "demo1",
- "id": 3,
- "keyword": "PURGE",
- "parameters": "TTL:360h",
- "startTime": "2019-06-20 18:33:40+00"
+ "id": 1,
+ "invalidationType": "REFETCH",
+ "startTime": "2021-11-09T01:02:03Z",
+ "ttlHours": 72
}
+
Response Structure
------------------
-:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-:createdBy: The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates
-:id: An integral, unique identifier for this job
-:keyword: A keyword that represents the operation being performed by
the job:
-
- PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
-
-:parameters: A string containing key/value pairs representing parameters
associated with the job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime: The date and time at which the job began, in a non-standard format
+:assetUrl: The :ref:`job-asset-url`
+:createdBy: The :ref:`job-created-by`
+:deliveryService: The :ref:`job-ds`
+:id: The :ref:`job-id`
+:invalidationType: The :ref:`job-invalidation-type`
+:ttlHours: The :ref:`job-ttl`
+:startTime: The :ref:`job-start-time`
.. code-block:: http
:caption: Response Example
HTTP/1.1 200 OK
- Access-Control-Allow-Credentials: true
- Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type,
Accept, Set-Cookie, Cookie
- Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
- Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
- Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54
GMT; Max-Age=3600; HttpOnly
- Whole-Content-Sha512:
+P1PTav4ZBoiQcCqQnUqf+J0dCfQgVj8mzzKtUCA69mWYulya9Bjf6BUd8Aro2apmpgPBkCEA5sITJV1tMYA0Q==
+ Permissions-Policy: interest-cohort=()
+ Set-Cookie: mojolicious=...
+ Vary: Accept-Encoding
X-Server-Name: traffic_ops_golang/
- Date: Wed, 19 Jun 2019 13:38:59 GMT
- Content-Length: 234
+ Date: Mon, 08 Nov 2021 16:43:35 GMT
+ Content-Length: 266
- { "alerts": [{
- "text": "Content invalidation job updated",
- "level": "success"
- }],
+ { "alerts": [
+ {
+ "text": "Invalidation request created for
http://origin.infra.ciab.test/.+, start: 2021-11-09 01:02:03 +0000 UTC end:
2021-11-12 01:02:03 +0000 UTC invalidation type: REFETCH",
+ "level": "success"
+ }
+ ],
"response": {
- "assetUrl": "http://origin.infra.ciab.test/.*";,
+ "assetUrl": "http://origin.infra.ciab.test/.+";,
"createdBy": "admin",
"deliveryService": "demo1",
- "id": 3,
- "keyword": "PURGE",
- "parameters": "TTL:360h",
- "startTime": "2019-06-20 18:33:40+00"
+ "id": 1,
+ "invalidationType": "REFETCH",
+ "startTime": "2021-11-09T01:02:03Z",
+ "ttlHours": 72
}}
``DELETE``
==========
-Deletes a content invalidation job.
+Deletes a :term:`Content Invalidation Job`.
-.. tip:: Content invalidation jobs that have passed their :abbr:`TTL (Time To
Live)` are not automatically deleted - for record-keeping purposes - so use
this to clean up old jobs that are no longer useful.
+.. tip:: :term:`Content Invalidation Jobs` that have passed their :abbr:`TTL
(Time To Live)` are not automatically deleted - for record-keeping purposes -
so use this to clean up old jobs that are no longer useful.
-.. caution:: Deleting a content invalidation job immediately triggers a
CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that content invalidation jobs become
active **immediately** at their ``startTime`` - unlike most other configuration
changes they do not wait for a :term:`Snapshot` or a "Queue Updates".
Furthermore, if the global :term:`Par [...]
+.. caution:: Deleting a :term:`Content Invalidation Job` immediately triggers
a CDN-wide revalidation update. In the case that the global :term:`Parameter`
``use_reval_pending`` has a value of exactly ``"0"``, this will instead trigger
a CDN-wide "Queue Updates". This means that :term:`Content Invalidation Jobs`
become active **immediately** at their ``startTime`` - unlike most other
configuration changes they do not wait for a :term:`Snapshot` or a "Queue
Updates". Furthermore, if the g [...]
-:Auth. Required: Yes
-:Roles Required: "operations" or "admin"\ [#tenancy]_
-:Permissions Required: JOB:DELETE, JOB:READ, DELIVERY-SERVICE:UPDATE,
DELIVERY-SERVICE:READ
-:Response Type: Object
+:Auth. Required: Yes
+:Roles Required: "operations" or "admin"\ [#tenancy]_
+:Permissions Required: JOB:DELETE, JOB:READ, DELIVERY-SERVICE:UPDATE,
DELIVERY-SERVICE:READ\ [#tenancy]_
+:Response Type: Object
Request Structure
-----------------
.. table:: Query Parameters
-
+------+----------+--------------------------------------------------------------------------------+
- | Name | Required | Description
|
-
+======+==========+================================================================================+
- | id | yes | The integral, unique identifier of the content
invalidation job being modified |
-
+------+----------+--------------------------------------------------------------------------------+
+
+------+----------+----------------------------------------------------------------------------------------+
+ | Name | Required | Description
|
+
+======+==========+========================================================================================+
+ | id | yes | The integral, unique identifier of the
:term:`Content Invalidation Job` being modified |
+
+------+----------+----------------------------------------------------------------------------------------+
.. code-block:: http
:caption: Request Example
- DELETE /api/4.0/jobs?id=3 HTTP/1.1
- Host: trafficops.infra.ciab.test
- User-Agent: python-requests/2.20.1
+ DELETE /api/4.0/jobs?id=1 HTTP/1.1
+ User-Agent: python-requests/2.25.1
Accept-Encoding: gzip, deflate
Accept: */*
Connection: keep-alive
Cookie: mojolicious=...
Content-Length: 0
+
Response Structure
------------------
-:assetUrl: A regular expression - matching URLs will be operated upon
according to ``keyword``
-:createdBy: The username of the user who initiated the job
-:deliveryService: The :ref:`ds-xmlid` of the :term:`Delivery Service` on which
this job operates
-:id: An integral, unique identifier for this job
-:keyword: A keyword that represents the operation being performed by
the job:
-
- PURGE
- This job will prevent caching of URLs matching the ``assetUrl``
until it is removed (or its Time to Live expires)
-
-:parameters: A string containing key/value pairs representing parameters
associated with the job - currently only uses Time to Live e.g. ``"TTL:48h"``
-:startTime: The date and time at which the job began, in a non-standard format
+:assetUrl: The :ref:`job-asset-url` of the deleted :term:`Content
Invalidation Job`
+:createdBy: The :ref:`job-created-by` of the deleted :term:`Content
Invalidation Job`
+:deliveryService: The :ref:`job-ds` of the deleted :term:`Content
Invalidation Job`
+:id: The :ref:`job-id`. of the deleted :term:`Content
Invalidation Job`
+:invalidationType: The :ref:`job-invalidation-type` of the deleted
:term:`Content Invalidation Job`
+:ttlHours: The :ref:`job-ttl` of the deleted :term:`Content
Invalidation Job`
+:startTime: The :ref:`job-start-time` of the deleted :term:`Content
Invalidation Job`
.. code-block:: http
:caption: Response Example
HTTP/1.1 200 OK
- Access-Control-Allow-Credentials: true
- Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type,
Accept, Set-Cookie, Cookie
- Access-Control-Allow-Methods: POST,GET,OPTIONS,PUT,DELETE
- Access-Control-Allow-Origin: *
Content-Encoding: gzip
Content-Type: application/json
- Set-Cookie: mojolicious=...; Path=/; Expires=Mon, 18 Nov 2019 17:40:54
GMT; Max-Age=3600; HttpOnly
- Whole-Content-Sha512:
FqfziXJYYwHb84Fac9+p4NEY3EsklYxe94wg/VOmlXk4R6l4SaPSh015CChPt/yT72MsWSETnIuRD9KtoK4I+w==
+ Permissions-Policy: interest-cohort=()
+ Set-Cookie: mojolicious=...
+ Vary: Accept-Encoding
X-Server-Name: traffic_ops_golang/
- Date: Tue, 18 Jun 2019 22:55:15 GMT
- Content-Length: 234
+ Date: Mon, 08 Nov 2021 16:54:32 GMT
+ Content-Length: 230
{ "alerts": [
{
@@ -380,15 +344,15 @@ Response Structure
}
],
"response": {
- "assetUrl": "http://origin.infra.ciab.test/.*";,
+ "assetUrl": "http://origin.infra.ciab.test/.+";,
"createdBy": "admin",
"deliveryService": "demo1",
- "id": 3,
- "keyword": "PURGE",
- "parameters": "TTL:36h",
- "startTime": "2019-06-20 18:33:40+00"
+ "id": 1,
+ "invalidationType": "REFETCH",
+ "startTime": "2021-11-09T01:02:03Z",
+ "ttlHours": 72
}}
-.. [#tenancy] When viewing content invalidation jobs, only those jobs that
operate on a :term:`Delivery Service` visible to the requesting user's
:term:`Tenant` will be returned. Likewise, creating a new content invalidation
job requires that the target :term:`Delivery Service` is modifiable by the
requesting user's :term:`Tenant`. However, when modifying or deleting an
existing content invalidation job, the operation can be completed if and only
if the requesting user's :term:`Tenant` i [...]
-.. [#readonly] This field must exist, but it must *not* be different than the
same field of the existing job (i.e. as seen in a GET_ response)
+.. [#tenancy] When viewing :term:`Content Invalidation Jobs`, only those jobs
that operate on a :term:`Delivery Service` visible to the requesting user's
:term:`Tenant` will be returned. Likewise, creating a new :term:`Content
Invalidation Jobs` requires that the target :term:`Delivery Service` is
modifiable by the requesting user's :term:`Tenant`. However, when modifying or
deleting an existing :term:`Content Invalidation Jobs`, the operation can be
completed if and only if the requesti [...]
+.. [#immutable] This field must exist, but it must *not* be different than the
same field of the existing job (i.e. as seen in a GET_ response). That is, this
cannot be changed.
diff --git a/docs/source/api/v4/servers_hostname_update_status.rst
b/docs/source/api/v4/servers_hostname_update_status.rst
index 6c63328..5aec43a 100644
--- a/docs/source/api/v4/servers_hostname_update_status.rst
+++ b/docs/source/api/v4/servers_hostname_update_status.rst
@@ -23,7 +23,7 @@
``GET``
=======
-Retrieves information regarding pending updates and revalidation jobs for a
given server
+Retrieves information regarding pending updates and :term:`Content
Invalidation Jobs` for a given server
:Auth. Required: Yes
:Roles Required: None
@@ -59,14 +59,14 @@ Each object in the returned array\ [#uniqueness]_ will
contain the following fie
:host_id: The integral, unique identifier for the server for
which the other fields in this object represent the pending updates and
revalidation status
:host_name: The (short) hostname of the server for which the other
fields in this object represent the pending updates and revalidation status
:parent_pending: A boolean telling whether or not any :term:`Topology`
ancestor or :term:`parent` of this server has pending updates
-:parent_reval_pending: A boolean telling whether or not any :term:`Topology`
ancestor or :term:`parent` of this server has pending revalidation jobs
-:reval_pending: ``true`` if the server has pending revalidation jobs,
``false`` otherwise
+:parent_reval_pending: A boolean telling whether or not any :term:`Topology`
ancestor or :term:`parent` of this server has pending :term:`Content
Invalidation Jobs`
+:reval_pending: ``true`` if the server has pending :term:`Content
Invalidation Jobs`, ``false`` otherwise
:status: The name of the status of this server
.. seealso:: :ref:`health-proto` gives more information on how these
statuses are used, and the ``GET`` method of the :ref:`to-api-statuses`
endpoint can be used to retrieve information about all server statuses
configured in Traffic Ops.
:upd_pending: ``true`` if the server has pending updates, ``false``
otherwise
-:use_reval_pending: A boolean which tells :term:`ORT` whether or not this
version of Traffic Ops should use pending revalidation jobs
+:use_reval_pending: A boolean which tells :term:`ORT` whether or not this
version of Traffic Ops should use pending :term:`Content Invalidation Jobs`
.. note:: This field was introduced to give :term:`ORT` the ability to
work with Traffic Control versions 1.x and 2.x seamlessly - as of Traffic
Control v3.0 there is no reason for this field to ever be ``false``.
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
index 7d7bd6f..84c564f 100644
--- a/docs/source/glossary.rst
+++ b/docs/source/glossary.rst
@@ -52,6 +52,14 @@ Glossary
.. seealso:: For a more complete description of Cache Groups,
see the :ref:`cache-groups` overview section.
+ Content Invalidation Job
+ Content Invalidation Jobs
+ job
+ jobs
+ :dfn:`Content Invalidation Jobs` are a way to force
:term:`cache servers` to treat their cached content as stale (or even not in
cache at all).
+
+ .. seealso:: For a more complete description of Content
Invalidation Jobs, see the :ref:`jobs` overview section.
+
content routing
Directing clients (or client systems) to a particular location
or device in a location for optimal delivery of content See also :ref:`http-cr`
and :ref:`dns-cr`.
diff --git a/docs/source/overview/delivery_service_requests.rst
b/docs/source/overview/delivery_service_requests.rst
index 7f4f31c..9413ed0 100644
--- a/docs/source/overview/delivery_service_requests.rst
+++ b/docs/source/overview/delivery_service_requests.rst
@@ -60,6 +60,7 @@ The model for a :abbr:`DSR (Delivery Service Request)` in the
most recent versio
original: DeliveryService;
requested: DeliveryService;
}
+
.. _dsr-assignee:
Assignee
diff --git a/docs/source/overview/jobs.rst b/docs/source/overview/jobs.rst
new file mode 100644
index 0000000..6e8477a
--- /dev/null
+++ b/docs/source/overview/jobs.rst
@@ -0,0 +1,137 @@
+..
+..
+.. Licensed 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.
+..
+
+.. _jobs:
+
+*************************
+Content Invalidation Jobs
+*************************
+:dfn:`Content Invalidation Jobs`, or simply "jobs" as they are sometimes
known, are ways of forcing :term:`cache servers` to treat content as no longer
valid, bypassing their normal caching policies.
+
+In general, this *should* be unnecessary, because a well-behaved
:term:`Origin` *should* be setting its HTTP caching headers properly, so that
content is only considered valid for some appropriate time intervals.
Occasionally, however, an :term:`Origin` will be too optimistic with its
caching instructions, and when content needs to be updated, :term:`cache
servers` need to be informed that they must check back with the :term:`Origin`.
Content Invalidation Jobs allow this to be done for s [...]
+
+The model for Content Invalidation Job as API objects is given in
:ref:`jobs-model`.
+
+.. _jobs-model:
+
+.. code-block:: typescript
+ :caption: Content Invalidation Job as a Typescript interface.
+
+ /** This is the form used to create a new Content Invalidation Job */
+ interface ContentInvalidationJobCreationRequest {
+ deliveryService: string;
+ invalidationType: "REFRESH" | "REFETCH";
+ regex: `/${string}` | `\\/${string}`; // must also be a valid
RegExp
+ startTime: Date; // RFC3339 string
+ ttlHours: number;
+ }
+
+ /**
+ * This is the form used to return representations of Content
Invalidation
+ * Requests to clients.
+ */
+ interface ContentInvalidationJob {
+ assetUrl: string;
+ createdBy: string;
+ deliveryService: string;
+ id: number;
+ invalidationType: "REFRESH" | "REFETCH";
+ startTime: Date; // RFC3339 string
+ ttlHours: number;
+ }
+
+.. _job-asset-url:
+
+Asset URL
+---------
+This property only appears in responses from the :ref:`to-api` (and in the
bodies of ``PUT`` requests to :ref:`to-api-jobs`, where the scheme and
host/authority sections of the URL is held immutable). The :dfn:`Asset URL` is
constructed from the `Regular Expression`_ used in the creation of a Content
Invalidation Job and the :ref:`ds-origin-url` of the :term:`Delivery Service`
for which it was created. It is a URL that has a valid regular expression as
its path (and may not be "percent-e [...]
+
+.. _job-created-by:
+
+Created By
+----------
+The username of the user who created the Content Invalidation Job is stored as
the :dfn:`Created By` property of the Content Invalidation Job.
+
+.. _job-ds:
+
+Delivery Service
+----------------
+A Content Invalidation Job can only act on content for a single
:term:`Delivery Service` - invalidating content for multiple :term:`Delivery
Services` requires multiple Content Invalidation Jobs. The :dfn:`Delivery
Service` property of a Content Invalidation Job holds the :ref:`ds-xmlid` of
the :term:`Delivery Service` on which it operates.
+
+.. versionchanged:: 4.0
+ In earlier API versions, this property was allowed to be either the
integral, unique identifier of the target :term:`Delivery Service`, *or* its
:ref:`ds-xmlid` - this is no longer the case, but it should always be safe to
use the :ref:`ds-xmlid` in any case.
+
+.. _job-id:
+
+ID
+--
+The integral, unique identifier for the Content Invalidation Job, assigned to
it upon its creation.
+
+.. _job-invalidation-type:
+
+Invalidation Type
+-----------------
+:dfn:`Invalidation Type` defines how a :term:`cache server` should go about
ensuring that its cache is valid.
+
+The normal operating mode for a Content Invalidation Job is to force the
:term:`cache server` to send a request to the :term:`Origin` to verify that its
cache is valid. If that is the case, no extra work is done and business as
usual resumes. However, some :term:`Origins` are misconfigured and do not
respond as required by HTTP specification. In this case, it is strongly advised
to fix the :term:`Origin` so that it properly implements HTTP. However, if an
:term:`Origin` is sending cache- [...]
+
+The two values allowed for a Content Invalidation Job's Invalidation Type are:
+
+REFRESH
+ A :dfn:`REFRESH` Content Invalidation Job instructs :term:`cache
servers` to behave normally - when matching content is requested, send an
upstream request to (eventually) the :term:`Origin` with cache-controlling HTTP
headers, and trust the :term:`Origin`'s response. The vast majority of all
Content Invalidation Jobs should most likely use this Invalidation Type.
+REFETCH
+ Rather than treating the cached content as "stale", the :term:`cache
servers` processing a :dfn:`REFETCH` Content Invalidation Job should fetch the
cached content again, regardless of what the :term:`Origin` has to say about
the validity of their caches. These types of Content Invalidation Jobs cannot
be created without a proper "semi-global" :ref:`refetch_enabled Parameter
<parameter-name-refetch_enabled>`.
+
+.. caution:: A "REFETCH" Content Invalidation Job should be used **only** when
the :term:`Origin` is not properly configured to support HTTP caching, and will
return invalid or incorrect responses to conditional requests as described in
section 4.3.2 of :rfc:`7234`. In any other case, this will cause undo load on
both the :term:`Origin` and the requesting :term:`cache servers`, and "REFRESH"
should be used instead.
+
+.. _job-regex:
+
+Regular Expression
+------------------
+The :dfn:`Regular Expression` of a Content Invalidation Job defines the
content on which it acts. It is used to match URL *paths* (including the query
string - but **not** including document fragments, which are not sent in HTTP
requests) of content to be invalidated, and is combined with the
:ref:`ds-origin-url` of the :term:`Delivery Service` for which the Content
Invalidation Job was created to obtain a final pattern that is made available
as the `Asset URL`_.
+
+.. note:: While the :ref:`to-api` and :ref:`tp-overview` both require the
Regular Expression to begin with ``/`` (so that it matches URL paths), the
:ref:`to-api` allows optionally escaping this leading character with a
"backslash" :kbd:`\\`, while :ref:`tp-overview` does not. As ``/`` is not
syntactically important to regular expressions, the use of a leading :kbd:`\\`
should be avoided where possible, and is only allowed for legacy compatibility
reasons.
+
+.. table:: Aliases/Synonyms
+
+
+------------+--------------------------------------------------------------------------------+-------------------------------+
+ | Name | Use(s)
| Type |
+
+============+================================================================================+===============================+
+ | Path Regex | In Traffic Portal forms
| unchanged (String, str, etc.) |
+
+------------+--------------------------------------------------------------------------------+-------------------------------+
+ | regex | In raw :ref:`to-api` requests and responses, internally
in multiple components | unchanged (String, str, etc.) |
+
+------------+--------------------------------------------------------------------------------+-------------------------------+
+
+.. _job-start-time:
+
+Start Time
+----------
+Content Invalidation Jobs are planned in advance, by setting their :dfn:`Start
Time` to some point in the future (the :ref:`to-api` will refuse to create
Content Invalidation Jobs with a Start Time in the past). Content Invalidation
Jobs will have no effect until their Start Time.
+
+.. _job-ttl:
+
+TTL
+---
+The :dfn:`TTL` of a Content Invalidation Job defines how long a Content
Invalidation Job should remain in effect. This is generally expressed as an
integer number of hours.
+
+.. table:: Aliases/Synonyms
+
+
+------------+-----------------------------------------+----------------------------------------------------------------------+
+ | Name | Use(s) | Type
|
+
+============+=========================================+======================================================================+
+ | parameters | In legacy :ref:`to-api` versions | A string,
containing the TTL in the format :samp:`TTL:{Actual TTL}h` |
+
+------------+-----------------------------------------+----------------------------------------------------------------------+
+ | ttlHours | In :ref:`to-api` requests and responses | Unchanged
(unsigned integer number of hours) |
+
+------------+-----------------------------------------+----------------------------------------------------------------------+
diff --git a/docs/source/overview/profiles_and_parameters.rst
b/docs/source/overview/profiles_and_parameters.rst
index 6005489..ae22120 100644
--- a/docs/source/overview/profiles_and_parameters.rst
+++ b/docs/source/overview/profiles_and_parameters.rst
@@ -202,8 +202,8 @@ There is a special Profile of Type_ UNK_PROFILE that holds
global configuration
| | | recommended that
this be set on a production system.
|
+--------------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| use_reval_pending | global | When this
Parameter is present and its Value_ is exactly "1", Traffic Ops will separately
keep track of :term:`cache servers`' |
- | | | updates and
pending content invalidation jobs. This behavior should be enabled by default,
and disabling it, while still possible, is |
- | | | **EXTREMELY
DISCOURAGED**.
|
+ | | | updates and
pending :term:`Content Invalidation Jobs`. This behavior should be enabled by
default, and disabling it, while still |
+ | | | possible is
**EXTREMELY DISCOURAGED**.
|
+--------------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
| geolocation.polling.url | CRConfig.json | The location of
a geographic IP mapping database for Traffic Router instances to use.
|
+--------------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -215,14 +215,13 @@ There is a special Profile of Type_ UNK_PROFILE that
holds global configuration
| | | is MaxMind's
GeoIP2 database. The format of this :ref:`Parameter <parameters>`'s Value_ is:
|
| | | :file:`{Country
Code};{Latitude},{Longitude}`, e.g. ``US;37.751,-97.822``
|
+--------------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
- | maxRevalDurationDays | regex_revalidate.config | This
:ref:`Parameter <parameters>` sets the maximum duration, in days, for which a
content invalidation job may run. This is |
- | | | **extremely**
important, as there is currently no way to delete a content invalidation job
once it has been created. Furthermore, |
- | | | while there is
no restriction placed on creating multiple Parameters_ with this
:ref:`parameter-name` and `Config File`_ - |
- | | | potentially with
differing :ref:`Values <parameter-value>` - this is **EXTREMELY DISCOURAGED as
any** :ref:`Parameter <parameters>` |
+ | maxRevalDurationDays | regex_revalidate.config | This
:ref:`Parameter <parameters>` sets the maximum duration, in days, for which a
:term:`Content Invalidation Job` may run. |
+ | | | Furthermore,
while there is no restriction placed on creating multiple Parameters_ with this
:ref:`parameter-name` and `Config File` |
+ | | | - potentially
with differing :ref:`Values <parameter-value>` - this is **EXTREMELY
DISCOURAGED as any** :ref:`Parameter <parameters>` |
| | | **that has both
that** :ref:`parameter-name` **and** `Config File`_ **might be used when
generating any given** |
| | |
`regex_revalidate.config`_ **file for any given** :term:`cache server` **and
whenever such** Parameters_ **exist, the actual maximum |
- | | | duration for
content invalidation jobs is undefined, and CAN and WILL differ from server to
server, and configuration file to |
- | | | configuration
file.**
|
+ | | | duration for**
:term:`Content Invalidation Jobs` **is undefined, and CAN and WILL differ from
server to server, and configuration |
+ | | | file to
configuration file.**
|
+--------------------------+-------------------------+---------------------------------------------------------------------------------------------------------------------------------------+
@@ -708,6 +707,15 @@ header
.. caution:: If a single :ref:`Profile <profiles>` has multiple
"header" Parameters for the same `Config File`_ with different :ref:`Values
<parameter-value>`, the actual header is undefined (but will be one of those
Parameters' :ref:`Values <parameter-value>`).
+.. _parameter-name-refetch_enabled:
+
+refetch_enabled
+ When a Parameter by this Name exists, and has the `Config File`_ value
of exactly "global", then its Value_ *may* be used by Traffic Ops to decide
whether or not the "REFETCH" :ref:`job-invalidation-type` of :term:`Content
Invalidation Jobs` are allowed to be created. The Value_ "true"
(case-insensitive) indicates that such :term:`Content Invalidation Jobs`
*should* be allowed, while all other :ref:`Values <parameter-value>` indicate
they should not.
+
+ .. note:: Any leading or trailing whitespace in the Value_ of these
Parameters is ignored.
+
+ .. caution:: There is no limit to the number of these Parameters that
may exist, and no association to any existing Profiles_ is considered when
choosing which Parameter to use. If more than one Parameter with the Name
``refetch_enabled`` exists with the `Config File`_ "global", then the actual
Value_ used to determine if "REFETCH" :ref:`job-invalidation-type` of
:term:`Content Invalidation Jobs` are allowed to be created is undefined (but
will be the Value_ of one of said Parameters). [...]
+
.. _parameter-secure:
Secure
diff --git a/docs/source/tools/atstccfg.rst b/docs/source/tools/atstccfg.rst
index 5fb35fb..25ffafd 100644
--- a/docs/source/tools/atstccfg.rst
+++ b/docs/source/tools/atstccfg.rst
@@ -150,7 +150,7 @@ Options
.. option:: -y, --revalidate-only
- When given, :program:`atstccfg` will only emit files relevant for
updating content invalidation jobs. for Apache Traffic Server implementations,
this limits the output to be only files named ``regex_revalidate.config``. Has
no effect if :option:`--get-data` or
:option:`--set-queue-status`/:option:`--set-reval-status` is/are used.
+ When given, :program:`atstccfg` will only emit files relevant for
updating :term:`Content Invalidation Jobs`. for Apache Traffic Server
implementations, this limits the output to be only files named
``regex_revalidate.config``. Has no effect if :option:`--get-data` or
:option:`--set-queue-status`/:option:`--set-reval-status` is/are used.
Environment Variables
---------------------
diff --git a/lib/go-tc/invalidationjobs.go b/lib/go-tc/invalidationjobs.go
index a1d1488..f58b3fa 100644
--- a/lib/go-tc/invalidationjobs.go
+++ b/lib/go-tc/invalidationjobs.go
@@ -463,8 +463,12 @@ func (job *UserInvalidationJobInput) Validate(tx *sql.Tx)
error {
return nil
}
-const REFRESH = "REFRESH"
-const REFETCH = "REFETCH"
+// These are the allowed values for the InvalidationType of an
+// InvalidationJobCreateV4/InvalidationJobV4.
+const (
+ REFRESH = "REFRESH"
+ REFETCH = "REFETCH"
+)
// InvalidationJobsResponse is the type of a response from Traffic Ops to a
// request made to its /jobs API endpoint for v 4.0+
@@ -511,18 +515,16 @@ type InvalidationJobV40 struct {
StartTime time.Time `json:"startTime"`
}
+// String implements the fmt.Stringer interface by providing a textual
+// representation of the InvalidationJobV4.
func (job InvalidationJobV4) String() string {
-
- ID := strconv.FormatUint(job.ID, 10)
- TTLHours := strconv.FormatUint(uint64(job.TTLHours), 10)
- StartTime := job.StartTime.String()
-
- return
fmt.Sprintf("{\nID:\t\t\t\t\t%s,\nAssetURL:\t\t\t%s,\nCreatedBy:\t\t\t%s,\nDeliveryService:\t%s,\nTTLHours:\t\t\t%s,\nInvalidationType:\t%s,\nStartTime:\t\t\t%s,\n}",
- ID,
+ return fmt.Sprintf(`InvalidationJobV4{ID: %d, AssetURL: "%s",
CreatedBy: "%s", DeliveryService: "%s", TTLHours: %d, InvalidationType: "%s",
StartTime: "%s"}`,
+ job.ID,
job.AssetURL,
job.CreatedBy,
job.DeliveryService,
- TTLHours,
+ job.TTLHours,
job.InvalidationType,
- StartTime)
+ job.StartTime.Format(time.RFC3339),
+ )
}
diff --git a/lib/go-tc/invalidationjobs_test.go
b/lib/go-tc/invalidationjobs_test.go
index 864992d..652315c 100644
--- a/lib/go-tc/invalidationjobs_test.go
+++ b/lib/go-tc/invalidationjobs_test.go
@@ -22,6 +22,7 @@ package tc
import (
"fmt"
"testing"
+ "time"
"github.com/apache/trafficcontrol/lib/go-util"
)
@@ -66,3 +67,19 @@ func ExampleInvalidationJobInput_TTLHours_number() {
fmt.Println(ttl)
// Output: 2
}
+
+func ExampleInvalidationJobV4_String() {
+ t, _ := time.Parse(time.RFC3339, "2021-11-08T01:02:03Z")
+ j := InvalidationJobV4{
+ AssetURL: "https://example.com/.*";,
+ CreatedBy: "noone",
+ DeliveryService: "demo1",
+ ID: 5,
+ InvalidationType: REFETCH,
+ StartTime: t,
+ TTLHours: 72,
+ }
+
+ fmt.Println(j)
+ // Output: InvalidationJobV4{ID: 5, AssetURL: "https://example.com/.*";,
CreatedBy: "noone", DeliveryService: "demo1", TTLHours: 72, InvalidationType:
"REFETCH", StartTime: "2021-11-08T01:02:03Z"}
+}
