[Draft] proposal: state API spec

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. https://github.com/dapr/dapr/issues/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 commented 2 years ago

cc @beiwei30 @kevinten10

kevinten10 commented 2 years ago

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 commented 2 years ago

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 commented 2 years ago

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 commented 1 year ago

@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 commented 1 year ago

@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: https://github.com/dapr/dapr/issues/2817 https://github.com/dapr/sig-api/issues/3

looking forward to your work!

salaboy commented 1 year ago

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 commented 1 year ago

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 commented 10 months ago

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

dapr / sig-api