[Draft] proposal: state API spec

[seeflood]

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

[seeflood]

cc @beiwei30 @kevinten10

[kevinten10]

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

[beiwei30]

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.

[yaron2]

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

[salaboy]

@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

[seeflood]

@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!

[salaboy]

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

[yaron2]

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?

[salaboy]

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