search

boltlabs-inc / key-mgmt-spec

Formal specification for the key management project
MIT License
3 stars 2 forks source link

Add definition for "Operation" #104

Closed jrdngr closed 2 years ago

jrdngr commented 2 years ago

I found myself using the word "Operation" a lot when writing the client epic. We were trying to think of a better word for " "Workflow" and I think this is a good replacement.

I repurposed the definition for "Request" because I think it fits the most closely and removed the "Workflow/Flow" definition. I think "Request" already has a well-established networking definition and might cause confusion down the line.

"Operation" is a pretty common word as well, but it seems to always be context dependent in my experience.

indomitableSwan commented 2 years ago

I'm fine with "operation" instead of "workflow".

I'm less sure of using "operation" for "request". I understand that the term is overloaded, but "request" seems more intuitive to me in terms of capturing the semantics of key server behavior. Is the overloading here actually likely to cause confusion? I'd like to hear other peoples' thoughts on this renaming.

jrdngr commented 2 years ago

I'm less sure of using "operation" for "request". I understand that the term is overloaded, but "request" seems more intuitive to me in terms of capturing the semantics of key server behavior. Is the overloading here actually likely to cause confusion? I'd like to hear other peoples' thoughts on this renaming.

I think it depends on how our API evolves over time. Right now our only requests are the ones that create tonic channels so it probably won't come up in conversation a lot. If we end up with more regular gRPC endpoints that have params/responses or if we ever have a REST component to our API then I think it's going to be confusing.

I'd be in favor of dropping "Operation" and deleting "Workflow" since it seems to have the same definition as "Request". Are there any workflows that don't hit the key server?

I anticipate that local-only workflows are likely to be added in the future, which is why I didn't use the word "request" for "workflow".

indomitableSwan commented 2 years ago

I'm less sure of using "operation" for "request". I understand that the term is overloaded, but "request" seems more intuitive to me in terms of capturing the semantics of key server behavior. Is the overloading here actually likely to cause confusion? I'd like to hear other peoples' thoughts on this renaming.

I think it depends on how our API evolves over time. Right now our only requests are the ones that create tonic channels so it probably won't come up in conversation a lot. If we end up with more regular gRPC endpoints that have params/responses or if we ever have a REST component to our API then I think it's going to be confusing.

It seems that some overloading of terms is always going to happen if we continue to use generic terms like "request", "operation", "transaction", "functionality", etc. Perhaps the answer is to make sure that the implementation chooses more informative names, and add qualifying details to the specification, e.g., maybe "user request" instead of just "request".

I am also concerned about the level of implementation specifics to include in the spec, i.e., if we try to update the spec to be prescriptive as to specific names for our networking sessions, this is almost certainly going to end up out of sync from the implementation at some point. (There are already some examples of this happening, where I got the balance wrong.) The point of the specification is discussed in the README, but we're not attempting to define a standard for interoperability, so I think we don't need the specification to be quite so prescriptive, so much as understandable for auditors and developers. I'm not yet sure what the right balance is here and appreciate your continued feedback on this.

I'd be in favor of dropping "Operation" and deleting "Workflow" since it seems to have the same definition as "Request". Are there any workflows that don't hit the key server?

I anticipate that local-only workflows are likely to be added in the future, which is why I didn't use the word "request" for "workflow".

jrdngr commented 2 years ago

Closing this now that I've spent more time closely reading the spec. I think "Request" is fine given the way it's used in context.