Merge pull request #452 from arschles/use-cases

Adding use cases documentation

concepts/actors/README.md

@@ -1,6 +1,12 @@
 # Introduction to actors
 
-Dapr runtime provides an actor implementation which is based on Virtual Actor pattern. The Dapr actors API provides a single-threaded programming model leveraging the scalability and reliability guarantees provided by underlying platform on which Dapr is running.
+The [actor pattern](https://en.wikipedia.org/wiki/Actor_model) describes **actors** as the lowest-level "unit of computation". In other words, you write your code in a self-contained unit (called an actor) that receives messages and processes them one at a time, without any kind of concurrency or threading.
+
+While your code processes a message, it can send one or more messages to other actors, or create new actors. An underlying **runtime** manages how, when and where each actor runs, and also routes messages between actors.
+
+A large number of actors can execute simultaneously, and actors execute independently from each other.
+
+Dapr includes a runtime that specifically implements the [Virtual Actor pattern](https://www.microsoft.com/en-us/research/project/orleans-virtual-actors/). With Dapr's implementation, you write your Dapr actors according to the Actor model, and Dapr leverages the scalability and reliability guarantees that the underlying platform provides.
 
 ## Quick links
 
@@ -9,23 +15,16 @@ Dapr runtime provides an actor implementation which is based on Virtual Actor pa
 
 ## Contents
 
-- [Understanding Actors](#understanding-actors)
 - [Actors in Dapr](#actors-in-dapr)
 - [Actor Lifetime](#actor-lifetime)
 - [Distribution and Failover](#distribution-and-failover)
 - [Actor Communication](#actor-communication)
 
-## Understanding actors
-
-An actor is an isolated, independent unit of compute and state with single-threaded execution.
-
-The [actor pattern](https://en.wikipedia.org/wiki/Actor_model) is a computational model for concurrent or distributed systems in which a large number of these actors can execute simultaneously and independently of each other. Actors can communicate with each other and they can create more actors.
-
 ### When to use actors
 
-Dapr actors is an implementation of the actor design pattern. As with any software design pattern, the decision whether to use a specific pattern is made based on whether or not a software design problem fits the pattern.
+As with any other technology decision, you should decide whether to use actors based on the problem you're trying to solve.
 
-Although the actor design pattern can be a good fit to a number of distributed systems problems and scenarios, careful consideration of the constraints of the pattern and the framework implementing it must be made. As general guidance, consider the actor pattern to model your problem or scenario if:
+The actor design pattern can be a good fit to a number of distributed systems problems and scenarios, but the first thing you should consider are the constraints of the pattern. Generally speaking, consider the actor pattern to model your problem or scenario if:
 
 * Your problem space involves a large number (thousands or more) of small, independent, and isolated units of state and logic.
 * You want to work with single-threaded objects that do not require significant interaction from external components, including querying state across a set of actors.

concepts/bindings/README.md

@@ -1,14 +1,15 @@
 # Bindings
 
-Using bindings, you can trigger your app with events coming in from external systems, or invoke external systems.
-Bindings allow for on-demand, event-driven compute scenarios, and help developers with the following:
+Using bindings, you can trigger your app with events coming in from external systems, or invoke external systems. This building block provides several benefits for you and your code:
 
-* Remove the complexities of connecting to, and polling from, messaging systems such as queues, message buses, etc.
-* Focus on business logic and not the implementation details of how to interact with a system
-* Keep the code free from SDKs or libraries
-* Handles retries and failure recovery
+* Remove the complexities of connecting to, and polling from, messaging systems such as queues and message buses
+* Focus on business logic and not implementation details of how to interact with a system
+* Keep your code free from SDKs or libraries
+* Handle retries and failure recovery
 * Switch between bindings at run time
-* Enable portable applications where environment-specific bindings are set-up and no code changes are required
+* Build portable applications where environment-specific bindings are set-up and no code changes are required
+
+For a specific example, bindings would allow your microservice to respond to incoming Twilio/SMS messages without adding or configuring a third-party Twilio SDK, worrying about polling from Twilio (or using websockets, etc.).
 
 Bindings are developed independently of Dapr runtime. You can view and contribute to the bindings [here](https://github.com/dapr/components-contrib/tree/master/bindings).
 

concepts/publish-subscribe-messaging/README.md

@@ -1,11 +1,10 @@
 # Publish/Subscribe Messaging
 
-Dapr enables developers to design their application with a pub/sub pattern using a message broker, where event consumers and producers are decoupled from one another, and communicate by sending and receiving messages that are associated with a namespace, usually in the form of topics.
+The [publish/subscribe pattern](https://en.wikipedia.org/wiki/Publish%E2%80%93subscribe_pattern) allows your microservices to communicate with each other purely by sending messages. In this system, the **producer** of a message sends it to a **topic**, with no knowledge of what service will receive the message. A messages can even be sent if there's no consumer for it.
 
-This allows event producers to send messages to consumers that aren't running, and consumers to receive messages based on subscriptions to topics.
+Similarly, a **consumer** will receive messages from a topic without knowledge of what producer sent it. This pattern is especially useful when you need to decouple microservices from one another.
 
-Dapr provides At-Least-Once messaging guarantees, and integrates with various message brokers implementations.
-These implementations are pluggable, and developed outside of the Dapr runtime in [components-contrib](https://github.com/dapr/components-contrib/tree/master/pubsub).
+Dapr provides a publish/subscribe API that provides at-least-once guarantees and integrates with various message brokers implementations. These implementations are pluggable, and developed outside of the Dapr runtime in [components-contrib](https://github.com/dapr/components-contrib/tree/master/pubsub).
 
 ## Publish/Subscribe API
 
@@ -14,7 +13,7 @@ The API for Publish/Subscribe can be found in the [spec repo](../../reference/ap
 ## Behavior and guarantees
 
 Dapr guarantees At-Least-Once semantics for message delivery.
-That is, when an application publishes a message to a topic using the Publish/Subscribe API, it can assume the message is delivered at least once to any subscriber when the response status code from that endpoint is `200`, or returns no error if using the gRPC client.
+That means that when an application publishes a message to a topic using the Publish/Subscribe API, it can assume the message is delivered at least once to any subscriber when the response status code from that endpoint is `200`, or returns no error if using the gRPC client.
 
 The burden of dealing with concepts like consumer groups and multiple instances inside consumer groups is all catered for by Dapr.
 

concepts/secrets/README.md

@@ -1,7 +1,13 @@
 # Dapr secrets management
 
-Dapr offers developers a consistent way to extract application secrets, without needing to know the specifics of the secret store being used.
-Secret stores are components in Dapr. Dapr allows users to write new secret stores component implementations that can be used both to hold secrets for other Dapr components (for example secrets used by a state store components to read/write state) as well as serving the application with a dedicated secret building block API. Using the secrets building block API, you can easily read secrets that can be used by the application from a named secrets store. 
+Almost all non-trivial applications need to _securely_ store secret data like API keys, database passwords, and more. By nature, these secrets should not be checked into the version control system, but they also need to be accessible to code running in production. This is generally a hard problem, but it's critical to get it right. Otherwise, critical production systems can be compromised.
+
+Dapr's solution to this problem is the secrets API and secrets stores.
+
+Here's how it works:
+
+- Dapr is set up to use a **secret store** - a place to securely store secret data
+- Application code uses the standard Dapr secrets API to retrieve secrets.
 
 Some examples for secret stores include `Kubernetes`, `Hashicorp Vault`, `Azure KeyVault`. See [secret stores](https://github.com/dapr/components-contrib/tree/master/secretstores) for the list of supported stores.
 

concepts/security/README.md

@@ -1,14 +1,24 @@
 # Security
 
+This article addresses multiple security considerations when using Dapr in a distributed application including:
+
 - [Sidecar-to-App Communication](#sidecar-to-app-communication)
 - [Sidecar-to-Sidecar Communication](#sidecar-to-sidecar-communication)
-- [Sidecar-to-system-services-communication](#Sidecar-to-system-services-communication)
-- [Component namespace scopes and secrets](#Component-namespace-scopes-and-secrets)
+- [Sidecar-to-system-services-communication](#sidecar-to-system-services-communication)
+- [Component namespace scopes and secrets](#component-namespace-scopes-and-secrets)
 - [Network Security](#network-security)
 - [Bindings Security](#bindings-security)
 - [State Store Security](#state-store-security)
 - [Management Security](#management-security)
 
+Several of the areas above are addressed through encryption of data in transit. One of the security mechanisms that Dapr employs for encrypting data in transit is [mutual authentication TLS](https://en.wikipedia.org/wiki/Mutual_authentication) or mTLS. mTLS offers a few key features for network traffic inside your application:
+
+- Two way authentication - the client proving its identify to the server, and vice-versa
+- An encrypted channel for all in-flight communication, after two-way authentication is established  
+
+Mutual TLS is useful in almost all scenarios, but especially so for systems subject to regulations such as [HIPAA](https://en.wikipedia.org/wiki/Health_Insurance_Portability_and_Accountability_Act) and [PCI](https://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard).
+
+Dapr enables mTLS and all the features described in this document in your application with little to no extra code or complex configuration inside your production systems
 
 ## Sidecar-to-App communication
 

concepts/service-invocation/README.md

@@ -1,6 +1,8 @@
 # Service Invocation
 
-Dapr-enabled apps can communicate with each other through well-known endpoints in the form of http or gRPC messages.
+Using the service invocation API, your microservice can find and reliably communicate with other microservices in your system using standard protocols ([gRPC](https://grpc.io) or HTTP are currently supported). 
+
+Below is a high level overview of how Dapr's service invocation system works.
 
 ![Service Invocation Diagram](../../images/service-invocation.png)
 
@@ -23,7 +25,8 @@ The following describes items 1-6 again in the context of this sample:
 
 Steps 4-5 are the same as the list above.
 
-For more information, see:
+# Next Steps
 
-- The [Service Invocation API Spec](../../reference/api/service_invocation_api.md)
-- A [HowTo](../../howto/invoke-and-discover-services/README.md) on Service Invocation
+**If you're ready to get started**, follow this how-to guide on [how to get started with service invocation](https://github.com/dapr/docs/tree/master/howto/invoke-and-discover-services)
+
+If you'd like more technical detail on how service invocation works, move on to the [API Spec](../../reference/api/service_invocation_api.md)

concepts/state-management/README.md

@@ -1,6 +1,14 @@
 # State management
 
-Dapr makes it simple for you to store key/value data in a store of your choice.
+Dapr offers key/value storage APIs for state management. If a microservice uses state management, it can use these APIs to leverage any of the [supported state stores](https://github.com/dapr/docs/blob/master/howto/setup-state-store/supported-state-stores.md), without adding or learning a third party SDK.
+
+When using state management your application will also be able to leverage several other features that would otherwise be complicated and error-prone to build yourself such as:
+
+- Distributed concurrency and data consistency
+- Retry policies
+- Bulk [CRUD](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete) operations
+
+See below for a diagram of state management's high level architecture.
 
 ![State management](../../images/state_management.png)
 
@@ -17,7 +25,7 @@ Dapr makes it simple for you to store key/value data in a store of your choice.
 
 ## State management API
 
-Dapr provides reliable state management to applications through a state management buidling block API. Developers can use this API to retrieve, save and delete state values by providing keys.  
+Developers can use the state management API to retrieve, save and delete state values by providing keys. 
 
 Dapr data stores are components. Dapr ships with [Redis](https://redis.io
 ) out-of-box for local development in self hosted mode. Dapr allows you to plug in other data stores as components such as [Azure CosmosDB](https://azure.microsoft.com/services/cosmos-db/), [SQL Server](https://azure.microsoft.com/services/sql-database/), [AWS DynamoDB](https://aws.amazon.com/DynamoDB
@@ -32,7 +40,7 @@ Visit [State API](../../reference/api/state_api.md) for more information.
 
 Dapr allows developers to attach to a state operation request additional metadata that describes how the request is expected to be handled. For example, you can attach concurrency requirements, consistency requirements, and retry policy to any state operation requests.
 
-By default, your application should assume a data store is **eventually consistent** and uses a **last-write-wins** concurrency pattern. On the other hand, if you do attach metadata to your requests, Dapr passes the metadata along with the requests to the state store and expects the data store to fulfil the requests.
+By default, your application should assume a data store is **eventually consistent** and uses a **last-write-wins** concurrency pattern. On the other hand, if you do attach metadata to your requests, Dapr passes the metadata along with the requests to the state store and expects the data store to fulfill the requests.
 
 Not all stores are created equal. To ensure portability of your application, you can query the capabilities of the store and make your code adaptive to different store capabilities.
 
@@ -47,7 +55,7 @@ SQL Server | Yes | Yes | Yes
 
 ## Concurrency
 
-Dapr supports optimistic concurrency control (OCC) using ETags. When a state is requested, Dapr always attaches an **ETag** property to the returned state. And when the user code tries to update or delete a state, it's expected to attach the ETag through the **If-Match** header. The write operation can succeed only when the provided ETag matches with the ETag in the database.
+Dapr supports optimistic concurrency control (OCC) using ETags. When a state is requested, Dapr always attaches an **ETag** property to the returned state. And when the user code tries to update or delete a state, it's expected to attach the ETag through the **If-Match** header. The write operation can succeed only when the provided ETag matches with the ETag in the state store.
 
 Dapr chooses OCC because in many applications, data update conflicts are rare because clients are naturally partitioned by business contexts to operate on different data. However, if your application chooses to use ETags, a request may get rejected because of mismatched ETags. It's recommended that you use a [Retry Policy](#Retry-Policies) to compensate for such conflicts when using ETags.