[Draft] proposal: state API spec

Question

[Draft] proposal: state API spec

Closed this issue 10 months ago · 9 comments

seeflood commented 2 years ago

1. What

Write a spec for state API and describe how to implement it in grpc, http1.1 and http2 and even in-process invocation.

2. Spec

// TODO

3. Recommended implementation

gRPC

The existing proto file is the recommended implementation in gRPC.
dapr/dapr#4603

in-process invocation

The trick here is that we can compile the proto file into interfaces in different programming language.
And these generated interfaces are "recommended implementation of in-process invocation".

in golang

The generated interface is the recommended implementation:

type DaprServer interface {
	// Invokes a method on a remote Dapr app.
	InvokeService(context.Context, *InvokeServiceRequest) (*v1.InvokeResponse, error)
	// Gets the state for a specific key.
	GetState(context.Context, *GetStateRequest) (*GetStateResponse, error)
	// Gets a bulk of state items for a list of keys
	GetBulkState(context.Context, *GetBulkStateRequest) (*GetBulkStateResponse, error)
}

The reason we don't use the client interface is that it has too many opts ...grpc.CallOption, which are useless for in-process communication

type DaprClient interface {

	// Gets the state for a specific key.
	GetState(ctx context.Context, in *GetStateRequest, opts ...grpc.CallOption) (*GetStateResponse, error)
	// Gets a bulk of state items for a list of keys
	GetBulkState(ctx context.Context, in *GetBulkStateRequest, opts ...grpc.CallOption) (*GetBulkStateResponse, error)
	// Saves the state for a specific key.
	SaveState(ctx context.Context, in *SaveStateRequest, opts ...grpc.CallOption) (*emptypb.Empty, error)
	// Queries the state.
	QueryStateAlpha1(ctx context.Context, in *QueryStateRequest, opts ...grpc.CallOption) (*QueryStateResponse, error)
	// Deletes the state for a specific key.
	DeleteState(ctx context.Context, in *DeleteStateRequest, opts ...grpc.CallOption) (*emptypb.Empty, error)
	// Deletes a bulk of state items for a list of keys
	DeleteBulkState(ctx context.Context, in *DeleteBulkStateRequest, opts ...grpc.CallOption) (*emptypb.Empty, error)
	// Executes transactions for a specified store
	ExecuteStateTransaction(ctx context.Context, in *ExecuteStateTransactionRequest, opts ...grpc.CallOption) (*emptypb.Empty, error)
}

in java

The default protoc compiler can't compile proto files into java interfaces. We can modify the protoc compiler plugin to do it.

http 1.1

// TODO

Answer 1 · 2022-05-11T15:57:53.000Z

cc @beiwei30 @kevinten10

Answer 2 · 2022-05-16T03:14:54.000Z

I also think that the simple interface is more conducive to becoming the standard API.

in-process invocation
The trick here is that we can compile the proto file into interfaces in different programming language.
And these generated interfaces are "recommended implementation of in-process invocation".

Developing proto plugins is more complicated.

In other words, if everyone agrees with this design idea.

At present, It is also possible for us to manually maintain a set of interface in each language.

Just like dapr-sdk does:

In java-sdk, a set of java api interface is maintained
In python-sdk, a set of python api interface is maintained

Answer 3 · 2022-05-30T07:09:03.000Z

I failed to get the reason why an "in-process invocation" API is necessary. Should we focus on API talking gRPC and HTTP? After all, these APIs are used between dapr sidecar and main app.

Answer 4 · 2022-06-29T12:46:29.000Z

I failed to get the reason why an "in-process invocation" API is necessary. Should we focus on API talking gRPC and HTTP? After all, these APIs are used between dapr sidecar and main app.

Agree

Answer 5 · 2023-05-28T09:34:46.000Z

@seeflood @kevinten10 is there someone still actively working on this? I might start doing some work around Open API spec for Dapr Components, I am reaching out to see if there is already work that I should take a look at

Answer 6 · 2023-05-29T13:51:45.000Z

@salaboy Sorry for not updating, I'm busy with work recently and not working on this issue.
There are two related issues, maybe you have read them:
dapr/dapr#2817
#3

looking forward to your work!

Answer 7 · 2023-06-19T15:28:39.000Z

I will restart this issue.. and submit a PR with a simple statestore OpenAPI v3 spec. I am interested in having a simple first version that we can test against daprd and improve iteratively

Answer 8 · 2023-06-19T15:40:48.000Z

I will restart this issue.. and submit a PR with a simple statestore OpenAPI v3 spec. I am interested in having a simple first version that we can test against daprd and improve iteratively

What about generating the OpenAPI spec from the Dapr protos?

Answer 9 · 2023-09-07T14:11:46.000Z

I am closing this issue as we have a draft initial version for the state api in the repo. we can open a new issue to track progress on that spec file