• Home
• io.deephaven
• deephaven-proto-backplane-grpc
• 0.36.1
• source code

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

deephaven-proto-backplane-grpc.0.36.1.source-code.object.proto Maven / Gradle / Ivy

/*
 * Copyright (c) 2016-2022 Deephaven Data Labs and Patent Pending
 */
syntax = "proto3";

package io.deephaven.proto.backplane.grpc;

option java_multiple_files = true;
option optimize_for = SPEED;
option go_package = "github.com/deephaven/deephaven-core/go/internal/proto/object";

import "deephaven/proto/ticket.proto";

service ObjectService {

    /*
     * Fetches a server-side object as a binary payload and assorted other tickets pointing at
     * other server-side objects that may need to be read to properly use this payload. The binary
     * format is implementation specific, but the implementation should be specified by the "type"
     * identifier in the typed ticket.
     *
     * Deprecated in favor of MessageStream, which is able to handle the same content.
     */
    rpc FetchObject(FetchObjectRequest) returns (FetchObjectResponse) {
        option deprecated = true;
    }

    /*
     * Provides a generic stream feature for Deephaven instances to use to add arbitrary functionality.
     * Presently these take the form of "object type plugins", where server-side code can specify how
     * an object could be serialized and/or communicate with a client. This gRPC stream is somewhat lower level
     * than the plugin API, giving the server and client APIs features to correctly establish and
     * control the stream. At this time, this is limited to a "ConnectRequest" to start the call.
     *
     * The first message sent to the server is expected to have a ConnectRequest, indicating which
     * export ticket to connect to. It is an error for the client to attempt to connect to an object
     * that has no plugin for its object type installed.
     *
     * The first request sent by the client should be a ConnectRequest. No other client message should
     * be sent until the server responds. The server will respond with Data as soon as it is able (i.e.
     * once the object in question has been resolved and the plugin has responded), indicating that the
     * request was successful. After that point, the client may send Data requests.
     *
     * All replies from the server to the client contain Data instances. When sent from the server to
     * the client, Data contains a bytes payload created by the server implementation of the plugin,
     * and server-created export tickets containing any object references specified to be sent by the
     * server-side plugin. As server-created exports, they are already resolved, and can be fetched or
     * otherwise referenced right away. The client API is expected to wrap those tickets in appropriate
     * objects, and the client is expected to release those tickets as appropriate, according to the
     * plugin's use case. Note that it is possible for the "type" field to be null, indicating that
     * there is no corresponding ObjectType plugin for these exported objects. This limits the client
     * to specifying those tickets in a subsequent request, or releasing the ticket to let the object
     * be garbage collected on the server.
     *
     * All Data instances sent from the client likewise contain a bytes payload, and may contain
     * references to objects that already exist or may soon exist on the server, not just tickets sent
     * by this same plugin. Note however that if those tickets are not yet resolved, neither the current
     * Data nor subsequent requests can be processed by the plugin, as the required references can't be
     * resolved.
     *
     * Presently there is no explicit "close" message to send, but plugin implementations can devise
     * their own "half-close" protocol if they so choose. For now, if one end closes the connection,
     * the other is expected to follow suit by closing their end too. At present, if there is an error
     * with the stream, it is conveyed to the client in the usual gRPC fashion, but the server plugin
     * will only be informed that the stream closed.
     *
     */
    rpc MessageStream(stream StreamRequest) returns (stream StreamResponse) {}

    /*
     * Half of the browser-based (browser's can't do bidirectional streams without websockets)
     * implementation for MessageStream.
     */
    rpc OpenMessageStream(StreamRequest) returns (stream StreamResponse) {}
    /*
     * Other half of the browser-based implementation for MessageStream.
     */
    rpc NextMessageStream(StreamRequest) returns (BrowserNextResponse) {}
}

message FetchObjectRequest {
    io.deephaven.proto.backplane.grpc.TypedTicket source_id = 1;
}

message FetchObjectResponse {
    string type = 1;
    bytes data = 2;
    repeated io.deephaven.proto.backplane.grpc.TypedTicket typed_export_ids = 3;
}

/*
 * First payload to send on a MessageStream, indicating the object to connect to
 * on the server.
 */
message ConnectRequest {
    io.deephaven.proto.backplane.grpc.TypedTicket source_id = 1;
}

/*
 * A generic payload sent from the client to the server. The specific requirements and
 * guarantees are defined by the specific plugin.
 */
message ClientData {
    // The payload, may be empty.
    bytes payload = 1;

    /*
     * The typed references, may be empty.
     *
     * These references may be any ticket, resolved or not. This lets the client reference
     * objects that already exist on the server or are still pending. Note that pending
     * tickets require the server to wait until that object exists before passing this request
     * to the server plugin, and since messages are always processed in order, later requests
     * will also be delayed.
     */
    repeated io.deephaven.proto.backplane.grpc.TypedTicket references = 2;
}

/*
 * A generic payload sent from the server to the client. The specific requirements and
 * guarantees of this are defined by the specific plugin.
 */
message ServerData {
    // The payload, may be empty.
    bytes payload = 1;

    /*
     * The exported references, may be empty.
     *
     * To correctly free up unused server resources, clients must take care to release
     * these exports when they will no longer be used. A reference may be missing a type,
     * meaning that the object cannot be used as the source_id for a ConnectRequest, but
     * it may still be passed back to the server as part of ClientData references, and
     * it still needs to be released when no longer used.
     */
    repeated io.deephaven.proto.backplane.grpc.TypedTicket exported_references = 2;
}

/*
 * Client payload for the MessageStream.
 */
message StreamRequest {
    oneof message {
        // Indicates that this is the first request of the stream, asking to connect to
        // a specific object on the server.
        ConnectRequest connect = 1;
        // Data to pass to the object on the server.
        ClientData data = 2;
    }
}
/*
 * Server responses to the client. Currently can only be ServerData messages.
 */
message StreamResponse {
    oneof message {
        // Data to pass to the client about the object on the server.
        ServerData data = 1;
    }
}

message BrowserNextResponse {
}