From 25fcf40f3d22d681500db202ac2c63d387fb192e Mon Sep 17 00:00:00 2001 From: ocket8888 Date: Tue, 23 Jun 2020 09:20:07 -0600 Subject: [PATCH 1/7] Added Tags blueprint --- blueprints/tags.md | 218 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 218 insertions(+) create mode 100644 blueprints/tags.md diff --git a/blueprints/tags.md b/blueprints/tags.md new file mode 100644 index 0000000000..aea7a01939 --- /dev/null +++ b/blueprints/tags.md @@ -0,0 +1,218 @@ + +# Tags + +## Problem Description +Tags are a fairly long-requested feature; to be able to associate a key word or +phrase with a Delivery Service, or a user. Today, some organizations are abusing +the overloaded "description" properties of a Delivery Service to provide +comma-separated key words and phrases, essentially inventing their own tags by +forcing semantics on a field that does not have them. + +## Proposed Change +A new, incredibly simple object will be added to the data model: Tags. A Tag is +nothing more than a unique name, which can be associated with the following +objects: + +- Cache Groups +- Delivery Services +- Origins as they appear in Traffic Ops API requests and responses +- Physical Locations as they appear in Traffic Ops API requests and responses +- Profiles +- Servers as they appear in Traffic Ops API requests and responses +- Tenants as they appear in Traffic Ops API requests and responses +- Topologies as they appear in Traffic Ops API requests and responses +- Users as they appear in Traffic Ops API requests and responses + +### Traffic Portal Impact + + +### Traffic Ops Impact + + +#### REST API Impact + + +#### Client Impact + + +#### Data Model / Database Impact + + +### ORT Impact + + +### Traffic Monitor Impact + + +### Traffic Router Impact + + +### Traffic Stats Impact + + +### Traffic Vault Impact + + +### Documentation Impact + + +### Testing Impact + + +### Performance Impact + + +### Security Impact + + +### Upgrade Impact + + +### Operations Impact + + +### Developer Impact + + +## Alternatives + + +## Dependencies + + +## References + From 644b058b73195a282bfb56f1887b503864a70f0f Mon Sep 17 00:00:00 2001 From: ocket8888 Date: Tue, 23 Jun 2020 09:21:25 -0600 Subject: [PATCH 2/7] Added some more stuff to the tags blueprint --- blueprints/tags.md | 173 ++++++++++++++++++++++++--------------------- 1 file changed, 92 insertions(+), 81 deletions(-) diff --git a/blueprints/tags.md b/blueprints/tags.md index aea7a01939..a350d2ca18 100644 --- a/blueprints/tags.md +++ b/blueprints/tags.md @@ -40,94 +40,105 @@ objects: - Topologies as they appear in Traffic Ops API requests and responses - Users as they appear in Traffic Ops API requests and responses -### Traffic Portal Impact - +## Component Impact +The only impacted components will be Traffic Ops and Traffic Portal, as other +components are strictly not allowed to derive meaning from an object's Tags. ### Traffic Ops Impact - - -#### REST API Impact - +A new object will be added, the Tag, which will appear through the API like the +following TypeScript interface. + +```typescript +interface Tag { + name: string; +} +``` + +Further, the aforementioned object types - which may be referred to as "taggable +objects" - will all be augmented with a new property: Tags, which will be a set +of Tag Names. + +```typescript +interface Taggable { + tags: Set; +} +``` + +The Tags will be "shared" globally across all object types; that is, there are +not separate "server tags" and "Delivery Service tags", only Tags. + +#### Database Specifics +The suggested method for storing Tag data is with one table for storing what +Tags exist, and separate tables for each Taggable object to be paired with zero +or more Tags. + +The main Tag table ought to look like this: +```text + Table "public.tag" + Column | Type | Collation | Nullable | Default +--------+------+-----------+----------+--------- + name | text | | not null | +Indexes: + "tag_pkey" PRIMARY KEY, btree (name) +``` + +and as an example of an object-to-Tag relation table, the server-to-Tag relation +table should resemble this: +```text + Table "public.server_tag" + Column | Type | Collation | Nullable | Default +--------+--------+-----------+----------+--------- + tag | text | | not null | + server | bigint | | not null | +Indexes: + "server_tag_pkey" PRIMARY KEY, btree (tag, server) +Foreign-key constraints: + "server_tag_server_fkey" FOREIGN KEY (server) REFERENCES server(id) ON UPDATE CASCADE ON DELETE CASCADE + "server_tag_tag_fkey" FOREIGN KEY (tag) REFERENCES tag(name) ON UPDATE CASCADE ON DELETE CASCADE +``` + +#### API Impact +The actual amount of work to add Tags to all Taggable objects is rather large, +considering the number of endpoints that need to be changed, but each change is +quite non-invasive, and can all be done atomically without breaking any +functionality between them. + +The new Tags endpoint (`/tags`) shall support the HTTP request methods GET and +POST. A further endpoint, `/tags/\{\{Tag Name\}\}` will also be added that +supports GET, PUT and DELETE. + +##### `/tags` + +The GET method will retrieve representations of all Tag objects, and ought to +support the standard pagination methods. + +The POST method will create new tags from a request payload. The payload may be +either a single representation of a Tag, or a set thereof. In any case, no Tag +may be created with a Name of a Tag that already exists. Also, the Name of a Tag +is subject to the restrictions that it not be empty and contain only +alphanumeric characters. + +The PUT method will edit (change the name) of an existing Tag #### Client Impact - - -#### Data Model / Database Impact - - -### ORT Impact - - -### Traffic Monitor Impact - - -### Traffic Router Impact - - -### Traffic Stats Impact - - -### Traffic Vault Impact - +### Traffic Portal Impact +A new UI section, complete with tables and forms for editing and creation, will +need to be added to accommodate the addition, editing and deletion of Tags. +Also, existing tables and forms for now-taggable objects will need to be updated +to accommodate the use of Tags. Each separate change can be done atomically, and +since the new collections need not be required, they can be done in non-invasive +fashion of arbitrary order (provided Tag manipulation itself is done first) +without disrupting any existing processes or data. ### Documentation Impact - +Tags will need to be documented in the data model, both themselves and on the +modeled objects which now contain them. Also, API endpoints will need to updated +to reflect the new return structures, where applicable. ### Testing Impact +## Performance Impact +For most objects this would merely add a column to the database query structure, +so the performance impact is expected to be negligible. -### Performance Impact - +## Upgrade Impact +This will require probably multiple database migrations (or possibly one if the +implementer is feeling brave), but should require no change to upgrade processes +nor cause any problems on roll-back, as the only lost data would be the new Tags +that would be inaccessible in an older version anyway. -### Security Impact - +## Operations Impact +Tags have no operational meaning, but operators may need to be made aware of +Tags' existences and different organizations may place their own, proprietary +importance on a Tag or Tags that they may then need to communicate to operators. -### Upgrade Impact - - -### Operations Impact - - -### Developer Impact - +## Developer Impact +Developers should be fairly free from impact, but may just need to be aware that +certain objects now have additional properties. ## Alternatives - - -## Dependencies - - -## References - +There are no alternatives of which I'm aware, other than the obvious "just not +doing tags". From 042a7a96578a2b595a1c26e21ba964c24df31079 Mon Sep 17 00:00:00 2001 From: ocket8888 Date: Tue, 23 Jun 2020 12:25:51 -0600 Subject: [PATCH 4/7] Relaxed name restrictions on Tags --- blueprints/tags.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/blueprints/tags.md b/blueprints/tags.md index ebfd34fd28..624c8deb13 100644 --- a/blueprints/tags.md +++ b/blueprints/tags.md @@ -189,7 +189,7 @@ Content-Length: 52 The request must be rejected with an appropriate HTTP Response code on the range [400, 500) if the request is not properly encoded as either a single Tag or an array thereof, any submitted Tag already exists, or any submitted Tag has a Name -containing non-alphanumeric characters. +containing characters that are not alphanumeric, =, or \_. **Response Structure** The response is an array - always, even if the request body contained only a @@ -300,9 +300,9 @@ modified. The request must be rejected with an appropriate HTTP response code on the interval [400, 500) if the Tag named in the request path does not exist, the new name is the name of a pre-existing Tag (excluding the Tag itself, which should -allow for successful completion as a no-op), the new name contains -non-alphanumeric characters, or the request body cannot be understood as a JSON -representation of a Tag. +allow for successful completion as a no-op), the new name contains characters +that are not alphanumeric, =, or \_, or the request body +cannot be understood as a JSON representation of a Tag. *Response Example* ```http From 91cc0f5fb6a2b1e12507291bd00a66ee9e4dc1b5 Mon Sep 17 00:00:00 2001 From: ocket8888 Date: Thu, 28 Jan 2021 11:24:01 -0700 Subject: [PATCH 5/7] Add paragraph about new tags to be created immediately --- blueprints/tags.md | 40 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) diff --git a/blueprints/tags.md b/blueprints/tags.md index 624c8deb13..44740f0c16 100644 --- a/blueprints/tags.md +++ b/blueprints/tags.md @@ -97,6 +97,46 @@ Foreign-key constraints: "server_tag_tag_fkey" FOREIGN KEY (tag) REFERENCES tag(name) ON UPDATE CASCADE ON DELETE CASCADE ``` +Also, the release that includes Tags should also include a database migration +that adds new tags based on existing Types, to make replacing them easier. + +Specifically, it should add Tags for: + +- Cache Group Types other than + - `ORG_LOC` + - `EDGE_LOC` + - `MID_LOC` + - `INFRA_LOC` (which will need to be created if it doesn't already exist) +- Server Types other than + - `EDGE` + - `MID` + - `CCR` + - `TRAFFIC_ROUTER` (which will need to be created if it doesn't already exist) + - `ORG` + - `INFLUXDB` (which will need to be created if it doesn't already exist) + - `RASCAL` + - `TRAFFIC_MONITOR` (which will need to be created if it doesn't already exist) + - `RIAK` + - `TRAFFIC_VAULT` (which will need to be created if it doesn't already exist) + - `ORG` + - `TRAFFIC_OPS` (which will need to be created if it doesn't already exist) + - `TRAFFIC_OPS_DB` (which will need to be created if it doesn't already exist) + - `TRAFFIC_STATS` (which will need to be created if it doesn't already exist) +- Delivery Service Types other than + - `HTTP` + - `HTTP_NO_CACHE` + - `HTTP_LIVE` + - `HTTP_LIVE_NATNL` + - `DNS` + - `DNS_LIVE` + - `DNS_LIVE_NATNL` + - `ANY_MAP` + - `CLIENT_STEERING` + - `STEERING` + +These created Tags should also be associated with the objects that have these +Types at the time they are created. + #### API Impact The actual amount of work to add Tags to all Taggable objects is rather large, considering the number of endpoints that need to be changed, but each change is From 97f61af5017dfda6c8ffad5c8b9f891185043dcf Mon Sep 17 00:00:00 2001 From: ocket8888 Date: Thu, 28 Jan 2021 11:27:22 -0700 Subject: [PATCH 6/7] Add server INFRA type --- blueprints/tags.md | 1 + 1 file changed, 1 insertion(+) diff --git a/blueprints/tags.md b/blueprints/tags.md index 44740f0c16..574c966f53 100644 --- a/blueprints/tags.md +++ b/blueprints/tags.md @@ -122,6 +122,7 @@ Specifically, it should add Tags for: - `TRAFFIC_OPS` (which will need to be created if it doesn't already exist) - `TRAFFIC_OPS_DB` (which will need to be created if it doesn't already exist) - `TRAFFIC_STATS` (which will need to be created if it doesn't already exist) + - `INFRA` (which will need to be created if it doesn't already exist) - Delivery Service Types other than - `HTTP` - `HTTP_NO_CACHE` From 44a19fda92a5664bf57fd1cd5c31670b9feb6e6f Mon Sep 17 00:00:00 2001 From: ocket8888 Date: Fri, 23 Apr 2021 13:28:06 -0600 Subject: [PATCH 7/7] Typo fix --- blueprints/tags.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/blueprints/tags.md b/blueprints/tags.md index 574c966f53..a75f473921 100644 --- a/blueprints/tags.md +++ b/blueprints/tags.md @@ -426,7 +426,7 @@ without disrupting any existing processes or data. ## Documentation Impact Tags will need to be documented in the data model, both themselves and on the -modeled objects which now contain them. Also, API endpoints will need to updated +modeled objects which now contain them. Also, API endpoints will need to be updated to reflect the new return structures, where applicable. ## Testing Impact