Skip to content

Commit 90cf4cf

Browse files
hhunter-mshhunter-ms
committed
toc restructure
Signed-off-by: Hannah Hunter <[email protected]>
1 parent 0d9b5a2 commit 90cf4cf

26 files changed

+269
-190
lines changed

‎daprdocs/content/en/developing-applications/building-blocks/_index.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,11 @@
11
---
22
type: docs
3-
title: "Building blocks"
4-
linkTitle: "Building blocks"
3+
title: "API building blocks"
4+
linkTitle: "API building blocks"
55
weight: 10
66
description: "Dapr capabilities that solve common development challenges for distributed applications"
77
---
88

9-
Get a high-level [overview of Dapr building blocks]({{< ref building-blocks-concept >}}) in the **Concepts** section.
9+
Get a high-level [overview of Dapr API building blocks]({{< ref building-blocks-concept >}}) in the **Concepts** section.
1010

1111
<img src="/images/buildingblocks-overview.png" alt="Diagram showing the different Dapr API building blocks" width=1000>

‎daprdocs/content/en/developing-applications/debugging/_index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
type: docs
33
title: "Debugging Dapr applications and the Dapr control plane"
44
linkTitle: "Debugging"
5-
weight: 60
5+
weight: 50
66
description: "Guides on how to debug Dapr applications and the Dapr control plane"
77
---

‎daprdocs/content/en/developing-applications/develop-components/_index.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
type: docs
3+
title: "Components"
4+
linkTitle: "Components"
5+
weight: 30
6+
description: "Learn more about developing Dapr's pluggable and middleware components"
7+
---

‎daprdocs/content/en/developing-applications/develop-components/develop-middleware.md

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
type: docs
3+
title: "How to: Author middleware components"
4+
linkTitle: "Middleware components"
5+
weight: 200
6+
description: "Learn how to develop middleware components"
7+
aliases:
8+
- /developing-applications/middleware/middleware-overview/
9+
- /concepts/middleware-concept/
10+
---
11+
12+
Dapr allows custom processing pipelines to be defined by chaining a series of middleware components. There are two places that you can use a middleware pipeline;
13+
14+
1) Building block APIs - HTTP middleware components are executed when invoking any Dapr HTTP APIs.
15+
2) Service-to-Service invocation - HTTP middleware components are applied to service-to-service invocation calls.
16+
17+
## Writing a custom middleware
18+
19+
Dapr uses [FastHTTP](https://github.com/valyala/fasthttp) to implement its HTTP server. Hence, your HTTP middleware needs to be written as a FastHTTP handler. Your middleware needs to implement a middleware interface, which defines a **GetHandler** method that returns **fasthttp.RequestHandler** and **error**:
20+
21+
```go
22+
type Middleware interface {
23+
GetHandler(metadata Metadata) (func(h fasthttp.RequestHandler) fasthttp.RequestHandler, error)
24+
}
25+
```
26+
27+
Your handler implementation can include any inbound logic, outbound logic, or both:
28+
29+
```go
30+
31+
func (m *customMiddleware) GetHandler(metadata Metadata) (func(fasthttp.RequestHandler) fasthttp.RequestHandler, error) {
32+
var err error
33+
return func(h fasthttp.RequestHandler) fasthttp.RequestHandler {
34+
return func(ctx *fasthttp.RequestCtx) {
35+
// inbound logic
36+
h(ctx) // call the downstream handler
37+
// outbound logic
38+
}
39+
}, err
40+
}
41+
```
42+
43+
## Related links
44+
45+
- [Component schema]({{< ref component-schema.md >}})
46+
- [Configuration overview]({{< ref configuration-overview.md >}})
47+
- [API middleware sample](https://github.com/dapr/samples/tree/master/middleware-oauth-google)

‎daprdocs/content/en/operations/components/pluggable-components/_index.md renamed to ‎daprdocs/content/en/developing-applications/develop-components/pluggable-components/_index.md

+4-4
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,9 @@
11
---
22
type: docs
3-
title: "Pluggable Components"
4-
linkTitle: "Pluggable Components"
3+
title: "Pluggable components"
4+
linkTitle: "Pluggable components"
55
description: "Guidance on how to work with pluggable components"
6-
weight: 4000
6+
weight: 100
77
aliases:
88
- "/operations/components/pluggable-components/pluggable-components-overview/"
9-
---
9+
---

‎daprdocs/content/en/developing-applications/develop-components/pluggable-components/develop-pluggable.md

+112
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,112 @@
1+
---
2+
type: docs
3+
title: "How to: Implement pluggable components"
4+
linkTitle: "Pluggable components"
5+
weight: 1100
6+
description: "Learn how to author and implement pluggable components"
7+
---
8+
9+
In this guide, you'll learn why and how to implement a [pluggable component]({{< ref pluggable-components-overview >}}). To learn how to configure and register a pluggable component, refer to [How to: Register a pluggable component]({{< ref pluggable-components-registration.md >}})
10+
11+
## Implement a pluggable component
12+
13+
In order to implement a pluggable component, you need to implement a gRPC service in the component. Implementing the gRPC service requires three steps:
14+
15+
### Find the proto definition file
16+
17+
Proto definitions are provided for each supported service interface (state store, pub/sub, bindings).
18+
19+
Currently, the following component APIs are supported:
20+
21+
- State stores
22+
- Pub/sub
23+
- Bindings
24+
25+
| Component | Type | gRPC definition | Built-in Reference Implementation | Docs |
26+
| :---------: | :--------: | :--------------: | :----------------------------------------------------------------------------: | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
27+
| State Store | `state` | [state.proto] | [Redis](https://github.com/dapr/components-contrib/tree/master/state/redis) | [concept]({{< ref "state-management-overview" >}}), [howto]({{< ref "howto-get-save-state" >}}), [api spec]({{< ref "state_api" >}}) |
28+
| Pub/sub | `pubsub` | [pubsub.proto] | [Redis](https://github.com/dapr/components-contrib/tree/master/pubsub/redis) | [concept]({{< ref "pubsub-overview" >}}), [howto]({{< ref "howto-publish-subscribe" >}}), [api spec]({{< ref "pubsub_api" >}}) |
29+
| Bindings | `bindings` | [bindings.proto] | [Kafka](https://github.com/dapr/components-contrib/tree/master/bindings/kafka) | [concept]({{< ref "bindings-overview" >}}), [input howto]({{< ref "howto-triggers" >}}), [output howto]({{< ref "howto-bindings" >}}), [api spec]({{< ref "bindings_api" >}}) |
30+
31+
Below is a snippet of the gRPC service definition for pluggable component state stores ([state.proto]):
32+
33+
```protobuf
34+
// StateStore service provides a gRPC interface for state store components.
35+
service StateStore {
36+
// Initializes the state store component with the given metadata.
37+
rpc Init(InitRequest) returns (InitResponse) {}
38+
// Returns a list of implemented state store features.
39+
rpc Features(FeaturesRequest) returns (FeaturesResponse) {}
40+
// Ping the state store. Used for liveness purposes.
41+
rpc Ping(PingRequest) returns (PingResponse) {}
42+
43+
// Deletes the specified key from the state store.
44+
rpc Delete(DeleteRequest) returns (DeleteResponse) {}
45+
// Get data from the given key.
46+
rpc Get(GetRequest) returns (GetResponse) {}
47+
// Sets the value of the specified key.
48+
rpc Set(SetRequest) returns (SetResponse) {}
49+
50+
51+
// Deletes many keys at once.
52+
rpc BulkDelete(BulkDeleteRequest) returns (BulkDeleteResponse) {}
53+
// Retrieves many keys at once.
54+
rpc BulkGet(BulkGetRequest) returns (BulkGetResponse) {}
55+
// Set the value of many keys at once.
56+
rpc BulkSet(BulkSetRequest) returns (BulkSetResponse) {}
57+
}
58+
```
59+
60+
The interface for the `StateStore` service exposes a total of 9 methods:
61+
62+
- 2 methods for initialization and components capability advertisement (Init and Features)
63+
- 1 method for health-ness or liveness check (Ping)
64+
- 3 methods for CRUD (Get, Set, Delete)
65+
- 3 methods for bulk CRUD operations (BulkGet, BulkSet, BulkDelete)
66+
67+
### Create service scaffolding
68+
69+
Use [protocol buffers and gRPC tools](https://grpc.io) to create the necessary scaffolding for the service. Learn more about these tools via [the gRPC concepts documentation](https://grpc.io/docs/what-is-grpc/core-concepts/).
70+
71+
These tools generate code targeting [any gRPC-supported language](https://grpc.io/docs/what-is-grpc/introduction/#protocol-buffer-versions). This code serves as the base for your server and it provides:
72+
- Functionality to handle client calls
73+
- Infrastructure to:
74+
- Decode incoming requests
75+
- Execute service methods
76+
- Encode service responses
77+
78+
The generated code is incomplete. It is missing:
79+
80+
- A concrete implementation for the methods your target service defines (the core of your pluggable component).
81+
- Code on how to handle Unix Socket Domain integration, which is Dapr specific.
82+
- Code handling integration with your downstream services.
83+
84+
Learn more about filling these gaps in the next step.
85+
86+
### Define the service
87+
88+
Provide a concrete implementation of the desired service. Each component has a gRPC service definition for its core functionality which is the same as the core component interface. For example:
89+
90+
- **State stores**
91+
92+
A pluggable state store **must** provide an implementation of the `StateStore` service interface.
93+
94+
In addition to this core functionality, some components might also expose functionality under other **optional** services. For example, you can add extra functionality by defining the implementation for a `QueriableStateStore` service and a `TransactionalStateStore` service.
95+
96+
- **Pub/sub**
97+
98+
Pluggable pub/sub components only have a single core service interface defined ([pubsub.proto]). They have no optional service interfaces.
99+
100+
- **Bindings**
101+
102+
Pluggable input and output bindings have a single core service definition on [bindings.proto]. They have no optional service interfaces.
103+
104+
After generating the above state store example's service scaffolding code using gRPC and protocol buffers tools, you can define concrete implementations for the 9 methods defined under `service StateStore`, along with code to initialize and communicate with your dependencies.
105+
106+
This concrete implementation and auxiliary code are the **core** of your pluggable component. They define how your component behaves when handling gRPC requests from Dapr.
107+
108+
## Next steps
109+
110+
- Get started with developing .NET pluggable component using this [sample code](https://github.com/dapr/samples/tree/master/pluggable-components-dotnet-template)
111+
- [Review the pluggable components overview]({{< ref pluggable-components-overview.md >}})
112+
- [Learn how to register your pluggable component]({{< ref pluggable-components-registration >}})

‎daprdocs/content/en/developing-applications/develop-components/pluggable-components/pluggable-components-overview.md

+69
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,69 @@
1+
---
2+
type: docs
3+
title: "Pluggable components overview"
4+
linkTitle: "Overview"
5+
weight: 1000
6+
description: "Overview of pluggable component anatomy and supported component types"
7+
---
8+
9+
Pluggable components are components that are not included as part the runtime, as opposed to the built-in components included with `dapr init`. You can configure Dapr to use pluggable components that leverage the building block APIs, but are registered differently from the [built-in Dapr components](https://github.com/dapr/components-contrib).
10+
11+
<img src="/images/concepts-building-blocks.png" width=400>
12+
13+
## Pluggable components vs. built-in components
14+
15+
Dapr provides two approaches for registering and creating components:
16+
17+
- The built-in components included in the runtime and found in the [components-contrib repository ](https://github.com/dapr/components-contrib).
18+
- Pluggable components which are deployed and registered independently.
19+
20+
While both registration options leverage Dapr's building block APIs, each has a different implementation processes.
21+
22+
| Component details | [Built-in Component](https://github.com/dapr/components-contrib/blob/master/docs/developing-component.md) | Pluggable Components |
23+
| ---------------------------- | :--------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
24+
| **Language** | Can only be written in Go | [Can be written in any gRPC-supported language](https://grpc.io/docs/what-is-grpc/introduction/#protocol-buffer-versions) |
25+
| **Where it runs** | As part of the Dapr runtime executable | As a distinct process or container in a pod. Runs separate from Dapr itself. |
26+
| **Registers with Dapr** | Included into the Dapr codebase | Registers with Dapr via Unix Domain Sockets (using gRPC ) |
27+
| **Distribution** | Distributed with Dapr release. New features added to component are aligned with Dapr releases | Distributed independently from Dapr itself. New features can be added when needed and follows its own release cycle. |
28+
| **How component is activated** | Dapr starts runs the component (automatic) | User starts component (manual) |
29+
30+
## Why create a pluggable component?
31+
32+
Pluggable components prove useful in scenarios where:
33+
34+
- You require a private component.
35+
- You want to keep your component separate from the Dapr release process.
36+
- You are not as familiar with Go, or implementing your component in Go is not ideal.
37+
38+
## Features
39+
40+
### Implement a pluggable component
41+
42+
In order to implement a pluggable component, you need to implement a gRPC service in the component. Implementing the gRPC service requires three steps:
43+
44+
1. Find the proto definition file
45+
1. Create service scaffolding
46+
1. Define the service
47+
48+
Learn more about [how to develop and implement a pluggable component]({{< ref develop-pluggable.md >}})
49+
50+
### Leverage multiple building blocks for a component
51+
52+
In addition to implementing multiple gRPC services from the same component (for example `StateStore`, `QueriableStateStore`, `TransactionalStateStore` etc.), a pluggable component can also expose implementations for other component interfaces. This means that a single pluggable component can simultaneously function as a state store, pub/sub, and input or output binding. In other words, you can implement multiple component interfaces into a pluggable component and expose them as gRPC services.
53+
54+
While exposing multiple component interfaces on the same pluggable component lowers the operational burden of deploying multiple components, it makes implementing and debugging your component harder. If in doubt, stick to a "separation of concerns" by merging multiple components interfaces into the same pluggable component only when necessary.
55+
56+
## Operationalize a pluggable component
57+
58+
Built-in components and pluggable components share one thing in common: both need a [component specification]({{< ref "components-concept.md#component-specification" >}}). Built-in components do not require any extra steps to be used: Dapr is ready to use them automatically.
59+
60+
In contrast, pluggable components require additional steps before they can communicate with Dapr. You need to first run the component and facilitate Dapr-component communication to kick off the registration process.
61+
62+
## Next steps
63+
64+
- [Implement a pluggable component]({{< ref develop-pluggable.md >}})
65+
- [Pluggable component registration]({{< ref "pluggable-components-registration" >}})
66+
67+
[state.proto]: https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/state.proto
68+
[pubsub.proto]: https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/pubsub.proto
69+
[bindings.proto]: https://github.com/dapr/dapr/blob/master/dapr/proto/components/v1/bindings.proto

‎daprdocs/content/en/developing-applications/integrations/_index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
type: docs
33
title: "Integrations"
44
linkTitle: "Integrations"
5-
weight: 10
5+
weight: 60
66
description: "Dapr integrations with other technologies"
77
---

‎daprdocs/content/en/developing-applications/local-development/_index.md

+7
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
type: docs
3+
title: "Local development"
4+
linkTitle: "Local development"
5+
weight: 40
6+
description: "Capabilities for developing Dapr applications locally"
7+
---

‎daprdocs/content/en/developing-applications/ides/_index.md renamed to ‎daprdocs/content/en/developing-applications/local-development/ides/_index.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,6 +2,6 @@
22
type: docs
33
title: "IDE support"
44
linkTitle: "IDE support"
5-
weight: 30
5+
weight: 200
66
description: "Support for common Integrated Development Environments (IDEs)"
77
---

‎daprdocs/content/en/developing-applications/ides/intellij.md renamed to ‎daprdocs/content/en/developing-applications/local-development/ides/intellij.md

File renamed without changes.

‎daprdocs/content/en/developing-applications/ides/vscode/_index.md renamed to ‎daprdocs/content/en/developing-applications/local-development/ides/vscode/_index.md

File renamed without changes.

‎daprdocs/content/en/developing-applications/ides/vscode/vscode-dapr-extension.md renamed to ‎daprdocs/content/en/developing-applications/local-development/ides/vscode/vscode-dapr-extension.md

File renamed without changes.

‎daprdocs/content/en/developing-applications/ides/vscode/vscode-how-to-debug-multiple-dapr-apps.md renamed to ‎daprdocs/content/en/developing-applications/local-development/ides/vscode/vscode-how-to-debug-multiple-dapr-apps.md

File renamed without changes.

‎daprdocs/content/en/developing-applications/ides/vscode/vscode-remote-dev-containers.md renamed to ‎daprdocs/content/en/developing-applications/local-development/ides/vscode/vscode-remote-dev-containers.md

File renamed without changes.

‎daprdocs/content/en/operations/components/component-scopes.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
type: docs
33
title: "How-To: Scope components to one or more applications"
44
linkTitle: "Scope access to components"
5-
weight: 300
5+
weight: 400
66
description: "Limit component access to particular Dapr instances"
77
---
88

‎daprdocs/content/en/operations/components/component-secrets.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
type: docs
33
title: "How-To: Reference secrets in components"
44
linkTitle: "Reference secrets in components"
5-
weight: 400
5+
weight: 500
66
description: "How to securly reference secrets from a component definition"
77
---
88

‎daprdocs/content/en/operations/components/component-updates.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22
type: docs
33
title: "Updating components"
44
linkTitle: "Updating components"
5-
weight: 250
5+
weight: 300
66
description: "Updating deployed components used by applications"
77
---
88

0 commit comments

Comments
 (0)