Skip to content

Commit

Permalink
Update draft-ramseyer-grow-peering-api.md
Browse files Browse the repository at this point in the history
Formatting.

Not sure this is better in long-term, but it is legible for now.
  • Loading branch information
jramseyer authored Dec 1, 2023
1 parent 361b9c4 commit c34f722
Showing 1 changed file with 57 additions and 57 deletions.
114 changes: 57 additions & 57 deletions draft-ramseyer-grow-peering-api.md
Original file line number Diff line number Diff line change
Expand Up @@ -70,70 +70,70 @@ PeeringDB OAuth will be the minimum requirement for authorization of API request
TODO: Update this spec, include API endpoints

## full list of endpoints:
ADD IX PEER
Augment IX PEER
TOPUP IX
NEW IX
REMOVE IX PEER
ADD PNI
AUGMENT PNI
REMOVE PNI
STATUS of PNI/IX CONNECTIONS
MAINTENANCE (notification) (no tickets)
ADD ROUTE SERVER
DELETE RS
QUERY for request status
On each call, there should be:
Rate limits, allowed senders, and other restriction options
Request source
* ADD IX PEER
* Augment IX PEER
* TOPUP IX
* NEW IX
* REMOVE IX PEER
* ADD PNI
* AUGMENT PNI
* REMOVE PNI
* STATUS of PNI/IX CONNECTIONS
* MAINTENANCE (notification) (no tickets)
* ADD ROUTE SERVER
* DELETE RS
* QUERY for request status
* On each call, there should be:
* Rate limits, allowed senders, and other restriction options
* Request source

## Request flow
1. AUTH phase: initiator makes an authenticated request to receiver via PeeringDB OAUTH. This provides the receiver with initiator’s credentials to verify who they say they are
2. REQUEST phase:
1. ADD: What is the initial information provided
1. Your ASN
1. Can use internal tools to check traffic levels
2. Cross reference with OAUTH data to verify ASN as the same one received in the OAUTH token
3. Can get prefix limit counters
1. Not needed in handshake but could be allowed as an optional flag
2. Peering Type: PNI or IX (Private or Public - however we want to brand it). This will be useful later when we want to differentiate between a public payload and a private one since they will look different
3. PeeringDB/IXP IDs that you want to peer on (this allows you to get the peering addresses)
2. REMOVE: What is the initial information provided
1. Your ASN
1. Cross reference with OAUTH data to verify ASN as the same one received in the OAUTH token
2. IXP ID
1. ADD: What is the initial information provided
* Your ASN
1. Can use internal tools to check traffic levels
2. Cross reference with OAUTH data to verify ASN as the same one received in the OAUTH token
3. Can get prefix limit counters
1. Not needed in handshake but could be allowed as an optional flag
* Peering Type: PNI or IX (Private or Public - however we want to brand it). This will be useful later when we want to differentiate between a public payload and a private one since they will look different
* PeeringDB/IXP IDs that you want to peer on (this allows you to get the peering addresses)
2. REMOVE: What is the initial information provided
1. Your ASN
* Cross reference with OAUTH data to verify ASN as the same one received in the OAUTH token
2. IXP ID
3. APPROVAL: What does the other side return?
1. Dictionary
1. Key: IXP ID
2. Value: Bool indicating whether or not peering is acceptable at this location
1. True: yes we can peer
2. False: no we can’t
1. Will return false if we’re already peered at that location
2. Counterproposal: suggest different configuration option. (in VLater)
2. Prefix limit counters (optional value)
3. TimeWindow: Time window indicating when sessions will be configured after being notified (may be 0 if sessions are already configured on receiver side)
4. isInboundFiltered: optional bool that indicates whether prefixes will be filtered inbound. If this is set to true the time window should be set to how long the prefixes will be filtered for.
5. isOutboundFiltered: optional bool that indicates whether prefixes will be filtered outbound. If this is set to true, the time window should be set to how long the prefixes will be filtered for. If the outbound limit is longer than the inbound limit time, the time window should be set to the max of inbound versus outbound.
1. Dictionary
1. Key: IXP ID
2. Value: Bool indicating whether or not peering is acceptable at this location
* True: yes we can peer
* False: no we can’t
* Will return false if we’re already peered at that location
* Counterproposal: suggest different configuration option. (in VLater)
2. Prefix limit counters (optional value)
3. TimeWindow: Time window indicating when sessions will be configured after being notified (may be 0 if sessions are already configured on receiver side)
4. isInboundFiltered: optional bool that indicates whether prefixes will be filtered inbound. If this is set to true the time window should be set to how long the prefixes will be filtered for.
5. isOutboundFiltered: optional bool that indicates whether prefixes will be filtered outbound. If this is set to true, the time window should be set to how long the prefixes will be filtered for. If the outbound limit is longer than the inbound limit time, the time window should be set to the max of inbound versus outbound.
4. Initiator removes sessions where receiver does not want to peer
1. For every IXP ID where bool = false, remove sessions from the dictionary. This handles the case where a user may initiate requests with all possible peering sessions and receiver only wants to peer in new locations. The initiator will then filter out duplicates before entering the CONFIG/MONITOR state.
1. For every IXP ID where bool = false, remove sessions from the dictionary. This handles the case where a user may initiate requests with all possible peering sessions and receiver only wants to peer in new locations. The initiator will then filter out duplicates before entering the CONFIG/MONITOR state.
5. CONFIG/MONITOR: Initiator waits for maximum time window and then notifies receiver for any outstanding sessions that have not been established
1. Initiator sends dictionary
1. IXP ID
2. Established: bool
3. Sent prefixes (0 if Established is false)
4. Received prefixes (0 if Established is false)
5. Accepted Prefixes
2. Receiver responds with dictionary
1. IXP ID
2. Established: bool
3. Sent prefixes
4. Received prefixes
5. Accepted Prefixes
3. If established = true, sentPrefixes > 0, and acceptedPrefixes > 0
1. You’re done
2. Initiator closes connection with a GOODBYE. Any subsequent followups must start this process over again. If the receiver has responded with a GOODBYE, then any subsequent monitoring calls will receive a GOODBYE. If a GOODBYE was presented erroneously, the initiator can make a new request asking the receiver to delete the session and retry.
4. Else, wait TimeWindow and retry
5. If initiator does not make a request in 3*TimeWindow or 1 week (whichever is longer), receiver automatically sends a GOODBYE and deletes the sessions on their side.
1. Initiator sends dictionary
1. IXP ID
2. Established: bool
3. Sent prefixes (0 if Established is false)
4. Received prefixes (0 if Established is false)
5. Accepted Prefixes
2. Receiver responds with dictionary
1. IXP ID
2. Established: bool
3. Sent prefixes
4. Received prefixes
5. Accepted Prefixes
3. If established = true, sentPrefixes > 0, and acceptedPrefixes > 0
1. You’re done
2. Initiator closes connection with a GOODBYE. Any subsequent followups must start this process over again. If the receiver has responded with a GOODBYE, then any subsequent monitoring calls will receive a GOODBYE. If a GOODBYE was presented erroneously, the initiator can make a new request asking the receiver to delete the session and retry.
4. Else, wait TimeWindow and retry
5. If initiator does not make a request in 3*TimeWindow or 1 week (whichever is longer), receiver automatically sends a GOODBYE and deletes the sessions on their side.

# API Endpoints and Specifications
TODO: list endpoints, both v0 and vLater
Expand Down

0 comments on commit c34f722

Please sign in to comment.