[maintenance] scd improve readability of OIR upsertion logic and OIR subscription handling

[Shastick]

The logic for creating and updating Operational Intent References (OIR) is central to the DSS's role.

The current work to address some open issues (#1056, #1074) revealed that the logic within this method is rather difficult to grasp, hindering its maintenance.

This issue's goals are:

• provide a high level description of what this method needs to do
• document how and where this method is tested
• provide a place to discuss approaches to simplify and improve that method's maintainability

Logic

The description below covers the logic of upsertOperationalIntentReference with respect to the handling of subscriptions and their cleanup when they are implicit.

Below, cipasicr() is a short-hand for check if previously attached subscription is implicit and can be removed

Subscription	Create OIR	Update OIR
None	1. check state, 2. create OIR	1. check state 2. update OIR 3. cipasicr()
Provided	1. check sub covers OIR. If not and is implicit: adapt, otherwise fail. 2 .create OIR	1. check sub covers OIR. If not and is implicit: adapt, otherwise fail 2. update OIR 3. cipasicr()
Request Implicit	1. create implicit sub 2. create OIR	1 .create implicit sub 2. update OIR 3. cipasicr()

See also @mickmis's comment with a table that focuses purely on the subscription handling:

	implicit old sub	explicit old sub	no old sub
implicit sub in params	delete old if no dependent OI	-	-
explicit sub in params	delete old if no dependent OI	-	-
no sub in params	delete old if no dependent OI	-	-
request new implicit sub in params	create new implicit sub, delete old if no dependent OI	create new implicit sub	create new implicit sub

Approaches

In a first step, we'll want to factor pieces of upsertOperationalIntentReference to into submethods. This should make the upsertion logic's behavior more tractable.

We should probably do so on the main branch, then incorporate the reorganisation into #1057

Testing

Subscription	Create OIR	Update OIR
None	OIRImplicitSubHandling	OIRImplicitSubHandling
Provided	OIRImplicitSubHandling, OIRSimple	OIRImplicitSubHandling
Request Implicit	OIRImplicitSubHandling	OIRImplicitSubHandling

	implicit old sub	explicit old sub	no old sub
existing implicit sub in params	OIRImplicitSubHandling	OIRImplicitSubHandling	OIRImplicitSubHandling
existing explicit sub in params	OIRImplicitSubHandling	OIRSimple	OIRSimple
no sub in params	OIRImplicitSubHandling	OIRSimple	OIRImplicitSubHandling
request new implicit sub in params	OIRImplicitSubHandling	OIRImplicitSubHandling	OIRImplicitSubHandling

The missing test scenarios (marked with a ❌) can likely be added to the OIRSimple scenario introduced by #1082

Considerations

While working on this, we should keep in mind the following:

• We have open work (#1059) that aims at reducing roundtrips to and from CRDB that will impact upsertOperationalIntentReference's logic
• We may need to move away from CRDB

The above are likely to impact the implementation: we should avoid spending too much efforts on parts that we know may disappear in the near future.

Tasks

• [x] reasonable code simplifications
• [x] determine test coverage
• [x] expand OIRImplicitSubHandling with test case for implicit sub expansion
• [x] expand OIRSimple (or OIRImplicitSubHandling if adequate) with missing test cases:
  • [x] (0, 9) oir creation with existing explicit sub: https://github.com/interuss/monitoring/pull/803
  • [x] (1) set existing implicit sub on existing OIR with explicit sub: https://github.com/interuss/monitoring/pull/820
  • [x] (2) set existing implicit sub on existing OIR without subscription: https://github.com/interuss/monitoring/pull/1026
  • [x] (3) set existing explicit sub on existing OIR with different explicit sub: https://github.com/interuss/monitoring/pull/803
  • [x] (4) set existing explicit sub on existing OIR without subscription: https://github.com/interuss/monitoring/pull/804
  • [x] (5) remove subscription from an ACCEPTED OIR that has an explicit subscription set: https://github.com/interuss/monitoring/pull/805
  • [x] (6) mutate an OIR without subscription while not providing any subscription parameters: https://github.com/interuss/monitoring/pull/1031
  • [x] (7) request new implicit subscription when mutating an OIR with existing explicit subscription: https://github.com/interuss/monitoring/pull/1036
  • [x] (8) request new implicit subscription when mutating an OIR without subscription: https://github.com/interuss/monitoring/pull/1038