Names and glossary of terms

[pvlugter]

Prompted by #377 and naming discussions, let's define the terms we'll be using for Cloudstate going forward.

Discussions have led to renaming stateless function -> action. And using workflow for coordinating actions.

[marcellanz]

Naming Failures
I link this contributors' call outcome where it was discussed how to handle failures and especially for this issue how to call failures. We might still find consistent names for them here.

[WadeWaldron]

I am working on trying to understand the naming right now. Here are the names that I am currently using.

• Proxy - This is the sidecar proxy that is deployed alongside Cloudstate. It consists of the following components:
  • Actors - Manage the flow of Commands/Events to/from the Entities defined in the Cloudstate Service.
  • Event Store - Essentially the database, but avoiding the use of that term because the capabilities of the database are intentionally limited.
• Service - This is the deployable unit that the user creates in their language of choice. It consists of the following components:
  • Entities - These map 1-1 to the Actors that live in the Proxy. The user code is executed inside the Entity.
• Client - This is the external system that calls into the Cloudstate system.
• Commands - These are the messages that flow from the Client into the Actor in the Proxy, and then get passed through to the Service to be processed by the Entity.
• Events - These are the messages that are emitted by the Entity as a result of processing a Command. They are persisted in the Event Store by the Actor associated with that Entity.

This is based on my incomplete understanding of Cloudstate, so feel free to correct any errors.

[sleipnir]

Hi @WadeWaldron, thanks for the contributions. I just have a few points to mention.
First, I think that when referring to Actors we make it clear that we are only talking about the Akka implementation of Cloudstate and not more generally the Cloudstate protocol, which can be implemented on top of other technologies in the future. I don't know if this is what we expect for the glossary of terms in this context. It might be worth having it separately, or making it clear that we are only referring to the Akka implementation.
Another small point is that at least I found an ambiguous definition when saying "the Entities defined in the Cloudstate Service" at this point I do not know if I am talking about the gRPC Service defined via Protobuf, the entity registration in Discover (via support language), or to the LBCS. I think that specific sentence could be more elaborated.
What do you think?

[WadeWaldron]

@sleipnir Thanks for the feedback. I actually wasn't aware that Cloudstate could be implemented on top of other technologies. That's very interesting. Does the protocol define something that acts as a more generic term than "Actor"? I.E. Does the Actor fill a particular role in the Cloudstate protocol?

I will admit the Service term is definitely overloaded. I just don't know what else to call it. If there's a better term, I would be happy to use it. I am using the term Service to refer to the deployed unit written in the user's language of choice.

[sleipnir]

@WadeWaldron Yes, indeed. Cloudstate is both a protocol and a reference implementation and in that sense I think it is always good to define the scope of each nomenclature well.

@pvlugter / @marcellanz , about the nomenclature of the service, I think we have discussed something similar before somewhere? Can you suggest something to help here?

[marcellanz]

I think this message https://groups.google.com/g/cloudstate/c/hALcsXiCpKk/m/XR-tl47cAQAJ started a thread where we iterated over service/entity/controller and, after this longer thread
#377
we went with action instead of naming controllers controllers and this last message by @pvlugter #377 (comment) sums ups the current understanding I think. There is still some wording left to be defined as Peter asked in this last post.

[sleipnir]

Thanks @marcellanz

[marcellanz]

Interestingly, I found right from the beginning looking solely from the spec, one has not to mention its underlying technology stack to understand. I found the spec itself enough to implement the user language support (at least for event sourcing) and I think when claiming by the project it rightfully should.

Also, the spec is a Draft PR since nearly a year, and not much fundamentally has changed. There are some questions to be clarified and I think once things settled, it will get more attention.

Over time, and if one gets to know Akka-(Cluster) I think, it seems clear that the reference implementation is based on it and also ideas from it are capture in the spec, but to understand or learn Cloudstate I think this is a detail not to be known for the user. I'm also looking forward to another implementation not based on Akka I think.

[sleipnir]

I absolutely agree