描述
After being in the Gitter chat on and off for a few years, I see variations of a recurring themes: "I want to do X but I am unsure how to accomplish this the Orleans way" or "I want to do X, should I use Y or Z?".
The current docs explain a lot of things, but they don't necessarily tie the functionality together in a cohesive manner. There are samples for this, but for the most part they are not production ready applications and are more usage demonstrations of some of main aspects of the Orleans public API surface.
I believe there to be a set of core use cases that probably cover 80% of usage scenarios in the wild. This is an attempt to capture those scenarios and document how to implement them The Orleans Way.
Templates
One of the great things about Orleans is the flexibility to configure almost every aspect of it. This benefit can also become a detriment by introducing the paradox of choice: when the number of choices increases, so does the difficulty of knowing what is best. I believe this introduces adoption hurdles when getting started with Orleans and configuring silos for production deployment and local development.
I know most, if not, all of this is covered by the docs, but it is spread out over multiple pages and can be overwhelming for a new user and can introduce friction for adoption. For example, the Project Setup page consists of multiple steps, all of which must be done properly in order to even get the project to compile and not crash at runtime
To remove friction, a set of dotnet new project templates would be created for common scenarios:
- Hosting a Silo alongside ASP.Net Core
- Hosting a Silo inside of a WorkerService
- Generating a classic 4-project solution (Console Client, Grain.Interfaces, Grains, Silo)
- Hosting a Silo (worker service) and a client (console) within Kuberenetes
- ... your suggestion here
The templates would take in some options, for example: --enable-transactions, --enable-azure-storage-tables-for-grain-storage, and --enable-mssql-for-grain-storage, --enable-tls, etc.
Recipes
It would be great to provide a library of use cases and how to accomplish them. We do have OrleansContrib/DesignPatterns, which are great, however the samples are stale and are abstracted at the level you'd expect in an architecture patterns book (I assume this was the point in of the repo).
The purpose of recipes would be to provide concrete step by step direction on how to accomplish certain tasks, explaining what they are doing, and why they are done this way, with links to the existing deeper dive docs.
A component of the recipies section would be a set of "I need X, use Y because of reasons", and provide guidance on how to accomplish it via recipes or documentation with explanations.
Some Examples:
- I need to receive events from a broker and send them to grains how should I do this?
- I need to call an external API that rate limits my calls, how do I do this?
- How can I call my grain via HTTP/gRPC?
- I saw Orleans doesn't have AuthN/AuthZ, how do I secure my silo and prevent rogue clients from connecting?
- Should I use Journaled Grains?
- How do I have an event sourced grain state?
- How do I modify multiple grains in a consistent way?
- When should I use
ReentrantversusAlwaysInterleave? - How can I enumerate my grains?
- ... your suggestion here
To supplement the recipe documentation, there would be corresponding dotnet new templates to generate the code needed for the use case.
Some example recipe templates I can think of off the top of my head:
- Work Queue: A grain with a persistent state that acts as a work queue using reminders
- Work Queue with Dispatcher: A grain with a persistent state that acts as a work queue using reminders to pass dequeued items to a target grain
- ... your suggestion here
My hope is that recipes will significantly decrease or remove the friction associated with Orleans adoption and remove some of the "gotchas" that lead to lost productivity.
I am looking for feedback in general and for scenarios/questions/template input from others that have spent time in the issue log and in the chat to help flesh out the topics.
I have identified some initial tasks for this work:
Recipes
- Introduce the Recipes section in docs with some basic use cases and answers gathered from chat
- .. TBD by discussion: choose a first recipe
Templates
- Create basic template that matches the Project Setup page
- .. TBD by discussion: choose other templates