You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@trafficcontrol.apache.org by GitBox <gi...@apache.org> on 2021/05/12 02:27:52 UTC
[GitHub] [trafficcontrol] limited commented on a change in pull request #5834: CDN Locks Blueprint
limited commented on a change in pull request #5834:
URL: https://github.com/apache/trafficcontrol/pull/5834#discussion_r630676391
##########
File path: blueprints/to-locks.md
##########
@@ -0,0 +1,279 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# CDN Traffic Ops Locks
+
+## Problem Description
+
+Currently, there is no way to guarantee that only your changes will make their way into a snapshot or queue updates
+for the servers of a CDN. If somebody else makes changes while you're in the middle of modifying your CDN components
+or properties, their changes will "dirty" your snapshot and change the integrity of the data that you'd expect in your
+snapshot. This could result in data mismatches and inconsistencies.
+
+CDN locks will serve as a way to avoid data corruption in snapshots and queue update activities by ensuring
+that only the intended user(s) is able to pass their changes to the snapshot/ queue updates. By placing locks
+on a CDN, a user can essentially block out other users from modifying data that would dirty their view of the
+CDN.
+
+This will be an optional feature in Traffic Ops/ Traffic Portal, which can be made use of by a user for their
+own guarantee of a "clean slate".
+
+## Proposed Change
+
+We propose a locking mechanism by which you can guarantee the exclusivity of your changes.
+With CDN locks, you can ensure one or both of the following conditions:
+- Only you can make changes and snap/ queue your CDN (exclusive locks)
+- Anybody can make changes but only you can snap/ queue your CDN (shared locks)
+
+`Exclusive` locks will help in cases where you are not collaborating with other users on the changes that you are
+making to a CDN. We anticipate all automated scripts and cron jobs to make use of these exclusive locks.
+
+The second category of locks is `shared` locks. This will be useful in a scenario when a group of users is working
+on different parts of a CDN, but their changes are not related to each other. In such a case, any number of users can
+grab the shared lock and make changes on the CDN. However, only the first user who grabbed the shared lock can actually
+snap/ queue updates on the CDN. This way, the first user to grab the lock still has the chance to review the changes, and
+also ensure that nobody else snaps/ queues the CDN before they are done with their intended modifications.
+
+There is also the third option of not using locks at all, in which case, the software will behave exactly the way it does
+today, that is, no safety that your changes will not be corrupted by somebody else before you snap/ queue.
+
+For unlocking a CDN under normal circumstances, only the user who has acquired the lock can unlock it (both shared
+and exclusive). However, in the rare case that a user `A` forgets to unlock a CDN, an `admin` role user can unlock
+the CDN on behalf of user `A`.
Review comment:
Can any user lock a CDN?
##########
File path: blueprints/to-locks.md
##########
@@ -0,0 +1,279 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# CDN Traffic Ops Locks
+
+## Problem Description
+
+Currently, there is no way to guarantee that only your changes will make their way into a snapshot or queue updates
+for the servers of a CDN. If somebody else makes changes while you're in the middle of modifying your CDN components
+or properties, their changes will "dirty" your snapshot and change the integrity of the data that you'd expect in your
+snapshot. This could result in data mismatches and inconsistencies.
+
+CDN locks will serve as a way to avoid data corruption in snapshots and queue update activities by ensuring
+that only the intended user(s) is able to pass their changes to the snapshot/ queue updates. By placing locks
+on a CDN, a user can essentially block out other users from modifying data that would dirty their view of the
+CDN.
+
+This will be an optional feature in Traffic Ops/ Traffic Portal, which can be made use of by a user for their
+own guarantee of a "clean slate".
+
+## Proposed Change
+
+We propose a locking mechanism by which you can guarantee the exclusivity of your changes.
+With CDN locks, you can ensure one or both of the following conditions:
+- Only you can make changes and snap/ queue your CDN (exclusive locks)
+- Anybody can make changes but only you can snap/ queue your CDN (shared locks)
+
+`Exclusive` locks will help in cases where you are not collaborating with other users on the changes that you are
+making to a CDN. We anticipate all automated scripts and cron jobs to make use of these exclusive locks.
+
+The second category of locks is `shared` locks. This will be useful in a scenario when a group of users is working
+on different parts of a CDN, but their changes are not related to each other. In such a case, any number of users can
+grab the shared lock and make changes on the CDN. However, only the first user who grabbed the shared lock can actually
+snap/ queue updates on the CDN. This way, the first user to grab the lock still has the chance to review the changes, and
+also ensure that nobody else snaps/ queues the CDN before they are done with their intended modifications.
+
+There is also the third option of not using locks at all, in which case, the software will behave exactly the way it does
+today, that is, no safety that your changes will not be corrupted by somebody else before you snap/ queue.
+
+For unlocking a CDN under normal circumstances, only the user who has acquired the lock can unlock it (both shared
+and exclusive). However, in the rare case that a user `A` forgets to unlock a CDN, an `admin` role user can unlock
+the CDN on behalf of user `A`.
+
+### Traffic Portal Impact
+
+- Landing Page
+ - New "lock" icon to give the user the ability to lock a particular CDN
+ - A dropdown list that appears when you click the above mentioned lock icon, which lists the list of CDNs that you can lock
+ - A `Message` field that appears under the dropdown list that the user can populate with a custom message stating the reason behind locking the CDN
+ - A `Shared` field that can be set to `true` or `false` based on user requirement
+ - A CDN notification displaying which CDN is locked by which user
+ - An "unlock" option that appears next to the notification, only for the user who has locked the CDN
+ - A way for the `admin` user to be able to unlock CDNs on other users' behalf
+
+- Snapshot/ Queue Updates Page
+ - Disable the snap/ queue button if another user has the lock on that CDN.
+
+### Traffic Ops Impact
+
+`/cdn_locks`
+- List all CDN Locks
+- GET+POST+DELETE
+
+Traffic Ops will need to add the logic to check for locks before snapping/ queueing a CDN. It'll also need to account for
+`shared` vs `exclusive` locks, and forbid a user from snapping/ queueing a CDN if another user possesses a lock on that CDN.
+The following endpoints will need to handle the locks logic:
+- `/cachegroups/{{ID}}/queue_update`
+- `/cdns/{{ID}}/queue_update`
+- `/servers/{{hostname}}/queue_update`
+- `/snapshot`
+- `/topologies/{{name}}/queue_update`
+
+#### REST API Impact
+
+The following is the JSON representation of a `CDN_Lock` object:
+```JSON
+{
+ "username": "foo",
+ "cdn": "cdn1",
+ "message": "snapping cdn",
+ "shared": false,
+ "creator": true,
+ "lastUpdated": "2021-05-10T16:03:34-06:00"
+}
+```
+
+The following table describes the top level `CDN_Lock` object:
+
+| field | type | optionality | description |
+| ----------- | --------------------------- | ----------- | ----------------------------------------------------------------------------------------|
+| username | string | required | the user name of the user that wants to acquire a lock on the CDN |
+| cdn | string | required | the name of the CDN on which the lcok needs to be acquired |
+| message | string | optional | the message stating a reason behind locking the CDN |
+| shared | boolean | required | whether or not this is a shared lock |
+| creator | boolean | required | whether or not the requesting `username` is the first one to acquire a lock on `cdn`|
+| lastUpdated | time | required | the last time this lock was updated |
+
+**API constraints:**
+- a `username` and `cdn` combination must be unique if `shared` is set to `false`. In other words, there can be only one `exclusive`
+lock for a CDN
+- a CDN can have multiple `shared` locks
+- the `creator` will be set to `true` if the user is the first one acquiring a lock for the specified `cdn`
Review comment:
`owner` of the lock might be a more common term
##########
File path: blueprints/to-locks.md
##########
@@ -0,0 +1,279 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# CDN Traffic Ops Locks
+
+## Problem Description
+
+Currently, there is no way to guarantee that only your changes will make their way into a snapshot or queue updates
+for the servers of a CDN. If somebody else makes changes while you're in the middle of modifying your CDN components
+or properties, their changes will "dirty" your snapshot and change the integrity of the data that you'd expect in your
+snapshot. This could result in data mismatches and inconsistencies.
+
+CDN locks will serve as a way to avoid data corruption in snapshots and queue update activities by ensuring
+that only the intended user(s) is able to pass their changes to the snapshot/ queue updates. By placing locks
+on a CDN, a user can essentially block out other users from modifying data that would dirty their view of the
+CDN.
+
+This will be an optional feature in Traffic Ops/ Traffic Portal, which can be made use of by a user for their
+own guarantee of a "clean slate".
+
+## Proposed Change
+
+We propose a locking mechanism by which you can guarantee the exclusivity of your changes.
+With CDN locks, you can ensure one or both of the following conditions:
+- Only you can make changes and snap/ queue your CDN (exclusive locks)
+- Anybody can make changes but only you can snap/ queue your CDN (shared locks)
+
+`Exclusive` locks will help in cases where you are not collaborating with other users on the changes that you are
+making to a CDN. We anticipate all automated scripts and cron jobs to make use of these exclusive locks.
+
+The second category of locks is `shared` locks. This will be useful in a scenario when a group of users is working
+on different parts of a CDN, but their changes are not related to each other. In such a case, any number of users can
+grab the shared lock and make changes on the CDN. However, only the first user who grabbed the shared lock can actually
+snap/ queue updates on the CDN. This way, the first user to grab the lock still has the chance to review the changes, and
+also ensure that nobody else snaps/ queues the CDN before they are done with their intended modifications.
+
+There is also the third option of not using locks at all, in which case, the software will behave exactly the way it does
+today, that is, no safety that your changes will not be corrupted by somebody else before you snap/ queue.
+
+For unlocking a CDN under normal circumstances, only the user who has acquired the lock can unlock it (both shared
+and exclusive). However, in the rare case that a user `A` forgets to unlock a CDN, an `admin` role user can unlock
+the CDN on behalf of user `A`.
+
+### Traffic Portal Impact
+
+- Landing Page
+ - New "lock" icon to give the user the ability to lock a particular CDN
+ - A dropdown list that appears when you click the above mentioned lock icon, which lists the list of CDNs that you can lock
+ - A `Message` field that appears under the dropdown list that the user can populate with a custom message stating the reason behind locking the CDN
+ - A `Shared` field that can be set to `true` or `false` based on user requirement
+ - A CDN notification displaying which CDN is locked by which user
+ - An "unlock" option that appears next to the notification, only for the user who has locked the CDN
+ - A way for the `admin` user to be able to unlock CDNs on other users' behalf
+
+- Snapshot/ Queue Updates Page
+ - Disable the snap/ queue button if another user has the lock on that CDN.
+
+### Traffic Ops Impact
+
+`/cdn_locks`
+- List all CDN Locks
+- GET+POST+DELETE
+
+Traffic Ops will need to add the logic to check for locks before snapping/ queueing a CDN. It'll also need to account for
+`shared` vs `exclusive` locks, and forbid a user from snapping/ queueing a CDN if another user possesses a lock on that CDN.
+The following endpoints will need to handle the locks logic:
+- `/cachegroups/{{ID}}/queue_update`
+- `/cdns/{{ID}}/queue_update`
+- `/servers/{{hostname}}/queue_update`
+- `/snapshot`
+- `/topologies/{{name}}/queue_update`
+
+#### REST API Impact
+
+The following is the JSON representation of a `CDN_Lock` object:
+```JSON
+{
+ "username": "foo",
+ "cdn": "cdn1",
+ "message": "snapping cdn",
+ "shared": false,
+ "creator": true,
+ "lastUpdated": "2021-05-10T16:03:34-06:00"
+}
+```
+
+The following table describes the top level `CDN_Lock` object:
+
+| field | type | optionality | description |
+| ----------- | --------------------------- | ----------- | ----------------------------------------------------------------------------------------|
+| username | string | required | the user name of the user that wants to acquire a lock on the CDN |
+| cdn | string | required | the name of the CDN on which the lcok needs to be acquired |
+| message | string | optional | the message stating a reason behind locking the CDN |
+| shared | boolean | required | whether or not this is a shared lock |
+| creator | boolean | required | whether or not the requesting `username` is the first one to acquire a lock on `cdn`|
+| lastUpdated | time | required | the last time this lock was updated |
+
+**API constraints:**
+- a `username` and `cdn` combination must be unique if `shared` is set to `false`. In other words, there can be only one `exclusive`
+lock for a CDN
+- a CDN can have multiple `shared` locks
+- the `creator` will be set to `true` if the user is the first one acquiring a lock for the specified `cdn`
+- a user can snap/ queue a CDN only if the `creator` field corresponding to the `username` and `cdn` combination is `true`
+- a user can delete their `exclusive` lock whenever, since the user is the creator in this case
+- a user who is the creator cannot delete their `shared` lock until all other non-creator users have releases their shared locks for that CDN
Review comment:
what use cases/concerns is this addressing?
##########
File path: blueprints/to-locks.md
##########
@@ -0,0 +1,279 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# CDN Traffic Ops Locks
+
+## Problem Description
+
+Currently, there is no way to guarantee that only your changes will make their way into a snapshot or queue updates
+for the servers of a CDN. If somebody else makes changes while you're in the middle of modifying your CDN components
+or properties, their changes will "dirty" your snapshot and change the integrity of the data that you'd expect in your
+snapshot. This could result in data mismatches and inconsistencies.
+
+CDN locks will serve as a way to avoid data corruption in snapshots and queue update activities by ensuring
+that only the intended user(s) is able to pass their changes to the snapshot/ queue updates. By placing locks
+on a CDN, a user can essentially block out other users from modifying data that would dirty their view of the
+CDN.
+
+This will be an optional feature in Traffic Ops/ Traffic Portal, which can be made use of by a user for their
+own guarantee of a "clean slate".
+
+## Proposed Change
+
+We propose a locking mechanism by which you can guarantee the exclusivity of your changes.
+With CDN locks, you can ensure one or both of the following conditions:
+- Only you can make changes and snap/ queue your CDN (exclusive locks)
+- Anybody can make changes but only you can snap/ queue your CDN (shared locks)
+
+`Exclusive` locks will help in cases where you are not collaborating with other users on the changes that you are
+making to a CDN. We anticipate all automated scripts and cron jobs to make use of these exclusive locks.
+
+The second category of locks is `shared` locks. This will be useful in a scenario when a group of users is working
+on different parts of a CDN, but their changes are not related to each other. In such a case, any number of users can
+grab the shared lock and make changes on the CDN. However, only the first user who grabbed the shared lock can actually
+snap/ queue updates on the CDN. This way, the first user to grab the lock still has the chance to review the changes, and
+also ensure that nobody else snaps/ queues the CDN before they are done with their intended modifications.
+
+There is also the third option of not using locks at all, in which case, the software will behave exactly the way it does
+today, that is, no safety that your changes will not be corrupted by somebody else before you snap/ queue.
+
+For unlocking a CDN under normal circumstances, only the user who has acquired the lock can unlock it (both shared
+and exclusive). However, in the rare case that a user `A` forgets to unlock a CDN, an `admin` role user can unlock
+the CDN on behalf of user `A`.
+
+### Traffic Portal Impact
+
+- Landing Page
+ - New "lock" icon to give the user the ability to lock a particular CDN
+ - A dropdown list that appears when you click the above mentioned lock icon, which lists the list of CDNs that you can lock
+ - A `Message` field that appears under the dropdown list that the user can populate with a custom message stating the reason behind locking the CDN
+ - A `Shared` field that can be set to `true` or `false` based on user requirement
+ - A CDN notification displaying which CDN is locked by which user
+ - An "unlock" option that appears next to the notification, only for the user who has locked the CDN
+ - A way for the `admin` user to be able to unlock CDNs on other users' behalf
+
+- Snapshot/ Queue Updates Page
+ - Disable the snap/ queue button if another user has the lock on that CDN.
+
+### Traffic Ops Impact
+
+`/cdn_locks`
+- List all CDN Locks
+- GET+POST+DELETE
+
+Traffic Ops will need to add the logic to check for locks before snapping/ queueing a CDN. It'll also need to account for
+`shared` vs `exclusive` locks, and forbid a user from snapping/ queueing a CDN if another user possesses a lock on that CDN.
+The following endpoints will need to handle the locks logic:
+- `/cachegroups/{{ID}}/queue_update`
+- `/cdns/{{ID}}/queue_update`
+- `/servers/{{hostname}}/queue_update`
+- `/snapshot`
+- `/topologies/{{name}}/queue_update`
+
+#### REST API Impact
+
+The following is the JSON representation of a `CDN_Lock` object:
+```JSON
+{
+ "username": "foo",
+ "cdn": "cdn1",
+ "message": "snapping cdn",
+ "shared": false,
+ "creator": true,
+ "lastUpdated": "2021-05-10T16:03:34-06:00"
+}
+```
+
+The following table describes the top level `CDN_Lock` object:
+
+| field | type | optionality | description |
+| ----------- | --------------------------- | ----------- | ----------------------------------------------------------------------------------------|
+| username | string | required | the user name of the user that wants to acquire a lock on the CDN |
+| cdn | string | required | the name of the CDN on which the lcok needs to be acquired |
+| message | string | optional | the message stating a reason behind locking the CDN |
+| shared | boolean | required | whether or not this is a shared lock |
+| creator | boolean | required | whether or not the requesting `username` is the first one to acquire a lock on `cdn`|
+| lastUpdated | time | required | the last time this lock was updated |
+
+**API constraints:**
+- a `username` and `cdn` combination must be unique if `shared` is set to `false`. In other words, there can be only one `exclusive`
+lock for a CDN
+- a CDN can have multiple `shared` locks
+- the `creator` will be set to `true` if the user is the first one acquiring a lock for the specified `cdn`
+- a user can snap/ queue a CDN only if the `creator` field corresponding to the `username` and `cdn` combination is `true`
Review comment:
a user can snap/queue a CDN only if their username matches the `creator` username?
##########
File path: blueprints/to-locks.md
##########
@@ -0,0 +1,279 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# CDN Traffic Ops Locks
+
+## Problem Description
+
+Currently, there is no way to guarantee that only your changes will make their way into a snapshot or queue updates
+for the servers of a CDN. If somebody else makes changes while you're in the middle of modifying your CDN components
+or properties, their changes will "dirty" your snapshot and change the integrity of the data that you'd expect in your
+snapshot. This could result in data mismatches and inconsistencies.
+
+CDN locks will serve as a way to avoid data corruption in snapshots and queue update activities by ensuring
+that only the intended user(s) is able to pass their changes to the snapshot/ queue updates. By placing locks
+on a CDN, a user can essentially block out other users from modifying data that would dirty their view of the
+CDN.
+
+This will be an optional feature in Traffic Ops/ Traffic Portal, which can be made use of by a user for their
+own guarantee of a "clean slate".
+
+## Proposed Change
+
+We propose a locking mechanism by which you can guarantee the exclusivity of your changes.
+With CDN locks, you can ensure one or both of the following conditions:
+- Only you can make changes and snap/ queue your CDN (exclusive locks)
+- Anybody can make changes but only you can snap/ queue your CDN (shared locks)
+
+`Exclusive` locks will help in cases where you are not collaborating with other users on the changes that you are
+making to a CDN. We anticipate all automated scripts and cron jobs to make use of these exclusive locks.
+
+The second category of locks is `shared` locks. This will be useful in a scenario when a group of users is working
+on different parts of a CDN, but their changes are not related to each other. In such a case, any number of users can
+grab the shared lock and make changes on the CDN. However, only the first user who grabbed the shared lock can actually
+snap/ queue updates on the CDN. This way, the first user to grab the lock still has the chance to review the changes, and
+also ensure that nobody else snaps/ queues the CDN before they are done with their intended modifications.
+
+There is also the third option of not using locks at all, in which case, the software will behave exactly the way it does
+today, that is, no safety that your changes will not be corrupted by somebody else before you snap/ queue.
+
+For unlocking a CDN under normal circumstances, only the user who has acquired the lock can unlock it (both shared
+and exclusive). However, in the rare case that a user `A` forgets to unlock a CDN, an `admin` role user can unlock
+the CDN on behalf of user `A`.
+
+### Traffic Portal Impact
+
+- Landing Page
+ - New "lock" icon to give the user the ability to lock a particular CDN
+ - A dropdown list that appears when you click the above mentioned lock icon, which lists the list of CDNs that you can lock
+ - A `Message` field that appears under the dropdown list that the user can populate with a custom message stating the reason behind locking the CDN
+ - A `Shared` field that can be set to `true` or `false` based on user requirement
+ - A CDN notification displaying which CDN is locked by which user
+ - An "unlock" option that appears next to the notification, only for the user who has locked the CDN
+ - A way for the `admin` user to be able to unlock CDNs on other users' behalf
+
+- Snapshot/ Queue Updates Page
+ - Disable the snap/ queue button if another user has the lock on that CDN.
+
+### Traffic Ops Impact
+
+`/cdn_locks`
+- List all CDN Locks
+- GET+POST+DELETE
+
+Traffic Ops will need to add the logic to check for locks before snapping/ queueing a CDN. It'll also need to account for
+`shared` vs `exclusive` locks, and forbid a user from snapping/ queueing a CDN if another user possesses a lock on that CDN.
+The following endpoints will need to handle the locks logic:
+- `/cachegroups/{{ID}}/queue_update`
+- `/cdns/{{ID}}/queue_update`
+- `/servers/{{hostname}}/queue_update`
+- `/snapshot`
+- `/topologies/{{name}}/queue_update`
+
+#### REST API Impact
+
+The following is the JSON representation of a `CDN_Lock` object:
+```JSON
+{
+ "username": "foo",
+ "cdn": "cdn1",
+ "message": "snapping cdn",
+ "shared": false,
+ "creator": true,
+ "lastUpdated": "2021-05-10T16:03:34-06:00"
+}
+```
+
+The following table describes the top level `CDN_Lock` object:
+
+| field | type | optionality | description |
+| ----------- | --------------------------- | ----------- | ----------------------------------------------------------------------------------------|
+| username | string | required | the user name of the user that wants to acquire a lock on the CDN |
+| cdn | string | required | the name of the CDN on which the lcok needs to be acquired |
+| message | string | optional | the message stating a reason behind locking the CDN |
+| shared | boolean | required | whether or not this is a shared lock |
+| creator | boolean | required | whether or not the requesting `username` is the first one to acquire a lock on `cdn`|
+| lastUpdated | time | required | the last time this lock was updated |
+
+**API constraints:**
+- a `username` and `cdn` combination must be unique if `shared` is set to `false`. In other words, there can be only one `exclusive`
+lock for a CDN
+- a CDN can have multiple `shared` locks
+- the `creator` will be set to `true` if the user is the first one acquiring a lock for the specified `cdn`
+- a user can snap/ queue a CDN only if the `creator` field corresponding to the `username` and `cdn` combination is `true`
+- a user can delete their `exclusive` lock whenever, since the user is the creator in this case
+- a user who is the creator cannot delete their `shared` lock until all other non-creator users have releases their shared locks for that CDN
+- a user with at least `all-read` and `all-write` capabilities can delete the locks of other users on any CDN. The `all-write` capability will be modified
+to include a new capability `delete-all-locks`.
+
+Three new endpoints will be added for `GET`, `POST` and `DELETE` functionality with respect to CDN locks.
+##### GET `cdn_locks`
+
+response JSON:
+```JSON
+{
+ "response": [
+ {
+ "username": "foo",
+ "cdn": "cdn1",
+ "message": "snapping cdn",
+ "shared": true,
+ "creator": true,
+ "lastUpdated": "2021-05-10T16:03:34-06:00"
+ },
+ {
+ "username": "bar",
+ "cdn": "cdn2",
+ "message": "queue cdn",
+ "shared": false,
+ "creator": true,
+ "lastUpdated": "2021-05-10T17:04:34-06:00"
+ }
+ ]
+}
+```
+
+##### POST `cdn_locks`
+
+request JSON:
+```JSON
+{
+ "cdn": "bar",
+ "message": "snapping cdn",
+ "shared": false
+}
+```
+
+response JSON:
+```JSON
+{
+ "alerts": [
+ {
+ "text": "CDN lock acquired!",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "username": "foo",
+ "cdn": "bar",
+ "message": "snapping cdn",
+ "shared": false,
+ "creator": true,
+ "lastUpdated": "2021-05-10T17:05:30-06:00"
+ }
+}
+```
+
+##### `DELETE /cdn_locks?cdn=bar`
+
+response JSON:
+```JSON
+{
+ "alerts": [
+ {
+ "text": "Cdn lock deleted",
+ "level": "success"
+ }
+ ],
+ "response": {
+ "username": "foo",
+ "cdn": "bar",
+ "message": "snapping cdn",
+ "shared": false,
+ "creator": true,
+ "lastUpdated": "2021-05-10T17:05:30-06:00"
+ }
+}
+```
+
+#### Client Impact
+
+New Go client methods will be added for the `/cdn_locks` endpoints in order to write TO API tests for the new endpoints.
+
+#### Data Model / Database Impact
Review comment:
I didn't see any discussion of the actual implementation, so I'm curious.
How will the lock be implemented? Will you be using Postgres Advisory locks? If not, are there particular atomic operations you'll make use of to avoid race conditions in acquiring, evaluating, and releasing locks?
##########
File path: blueprints/to-locks.md
##########
@@ -0,0 +1,279 @@
+<!--
+Licensed to the Apache Software Foundation (ASF) under one
+or more contributor license agreements. See the NOTICE file
+distributed with this work for additional information
+regarding copyright ownership. The ASF licenses this file
+to you under the Apache License, Version 2.0 (the
+"License"); you may not use this file except in compliance
+with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied. See the License for the
+specific language governing permissions and limitations
+under the License.
+-->
+# CDN Traffic Ops Locks
+
+## Problem Description
+
+Currently, there is no way to guarantee that only your changes will make their way into a snapshot or queue updates
+for the servers of a CDN. If somebody else makes changes while you're in the middle of modifying your CDN components
+or properties, their changes will "dirty" your snapshot and change the integrity of the data that you'd expect in your
+snapshot. This could result in data mismatches and inconsistencies.
+
+CDN locks will serve as a way to avoid data corruption in snapshots and queue update activities by ensuring
+that only the intended user(s) is able to pass their changes to the snapshot/ queue updates. By placing locks
+on a CDN, a user can essentially block out other users from modifying data that would dirty their view of the
+CDN.
+
+This will be an optional feature in Traffic Ops/ Traffic Portal, which can be made use of by a user for their
+own guarantee of a "clean slate".
+
+## Proposed Change
+
+We propose a locking mechanism by which you can guarantee the exclusivity of your changes.
+With CDN locks, you can ensure one or both of the following conditions:
+- Only you can make changes and snap/ queue your CDN (exclusive locks)
+- Anybody can make changes but only you can snap/ queue your CDN (shared locks)
+
+`Exclusive` locks will help in cases where you are not collaborating with other users on the changes that you are
+making to a CDN. We anticipate all automated scripts and cron jobs to make use of these exclusive locks.
+
+The second category of locks is `shared` locks. This will be useful in a scenario when a group of users is working
+on different parts of a CDN, but their changes are not related to each other. In such a case, any number of users can
+grab the shared lock and make changes on the CDN. However, only the first user who grabbed the shared lock can actually
+snap/ queue updates on the CDN. This way, the first user to grab the lock still has the chance to review the changes, and
+also ensure that nobody else snaps/ queues the CDN before they are done with their intended modifications.
+
+There is also the third option of not using locks at all, in which case, the software will behave exactly the way it does
+today, that is, no safety that your changes will not be corrupted by somebody else before you snap/ queue.
+
+For unlocking a CDN under normal circumstances, only the user who has acquired the lock can unlock it (both shared
+and exclusive). However, in the rare case that a user `A` forgets to unlock a CDN, an `admin` role user can unlock
+the CDN on behalf of user `A`.
+
+### Traffic Portal Impact
+
+- Landing Page
+ - New "lock" icon to give the user the ability to lock a particular CDN
+ - A dropdown list that appears when you click the above mentioned lock icon, which lists the list of CDNs that you can lock
+ - A `Message` field that appears under the dropdown list that the user can populate with a custom message stating the reason behind locking the CDN
+ - A `Shared` field that can be set to `true` or `false` based on user requirement
+ - A CDN notification displaying which CDN is locked by which user
+ - An "unlock" option that appears next to the notification, only for the user who has locked the CDN
+ - A way for the `admin` user to be able to unlock CDNs on other users' behalf
+
+- Snapshot/ Queue Updates Page
+ - Disable the snap/ queue button if another user has the lock on that CDN.
+
+### Traffic Ops Impact
+
+`/cdn_locks`
+- List all CDN Locks
+- GET+POST+DELETE
+
+Traffic Ops will need to add the logic to check for locks before snapping/ queueing a CDN. It'll also need to account for
+`shared` vs `exclusive` locks, and forbid a user from snapping/ queueing a CDN if another user possesses a lock on that CDN.
+The following endpoints will need to handle the locks logic:
+- `/cachegroups/{{ID}}/queue_update`
+- `/cdns/{{ID}}/queue_update`
+- `/servers/{{hostname}}/queue_update`
+- `/snapshot`
+- `/topologies/{{name}}/queue_update`
+
+#### REST API Impact
+
+The following is the JSON representation of a `CDN_Lock` object:
+```JSON
+{
+ "username": "foo",
+ "cdn": "cdn1",
+ "message": "snapping cdn",
+ "shared": false,
+ "creator": true,
+ "lastUpdated": "2021-05-10T16:03:34-06:00"
+}
+```
+
+The following table describes the top level `CDN_Lock` object:
+
+| field | type | optionality | description |
+| ----------- | --------------------------- | ----------- | ----------------------------------------------------------------------------------------|
+| username | string | required | the user name of the user that wants to acquire a lock on the CDN |
+| cdn | string | required | the name of the CDN on which the lcok needs to be acquired |
+| message | string | optional | the message stating a reason behind locking the CDN |
+| shared | boolean | required | whether or not this is a shared lock |
+| creator | boolean | required | whether or not the requesting `username` is the first one to acquire a lock on `cdn`|
+| lastUpdated | time | required | the last time this lock was updated |
+
+**API constraints:**
+- a `username` and `cdn` combination must be unique if `shared` is set to `false`. In other words, there can be only one `exclusive`
Review comment:
`cdn` by itself must be unique if the lock is `exclusive`, right?
(`user1`, `cdn`) and (`user2`, `cdn`) should not be allowed for an exclusive lock
For a shared lock, (`username`, `cdn`) must be unique.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org