syntax = "proto3";
package resource;

option go_package = "github.com/s4wave/spacewave/bldr/resource";

// ResourceService provides a set of stateful resources via an RPC service.
service ResourceService {
  // ResourceClient starts an instance of a client for the ResourceService,
  // yielding a new client ID. The client can use that ID for future RPCs
  // accessing the Resource tree. When the streaming RPC ends, references to
  // resources opened by the client will be released.
  rpc ResourceClient(stream ResourceClientRequest) returns (stream ResourceClientResponse) {
  }

  // ResourceRpc is a rpc request for an open resource handle.
  // Exposes service(s) depending on the resource type.
  // The first request selects a resource; one typed acknowledgement precedes data.
  rpc ResourceRpc(stream ResourceRpcPacket) returns (stream ResourceRpcPacket);

  // ResourceAttach allows a client to provide resources that server-side
  // RPC handlers can invoke via getAttachedRef(id). Session-only Init/Ack,
  // then resources registered via Add/AddAck. After Init/Ack, mux_data
  // carries yamux frames for all attached resources.
  rpc ResourceAttach(stream ResourceAttachRequest)
    returns (stream ResourceAttachResponse);
}

// ResourceFailureCode controls lifecycle recovery independently of diagnostics.
enum ResourceFailureCode {
  RESOURCE_FAILURE_CODE_UNKNOWN = 0;
  RESOURCE_FAILURE_CODE_RESOURCE_NOT_FOUND = 1;
  RESOURCE_FAILURE_CODE_CLIENT_RELEASED = 2;
  RESOURCE_FAILURE_CODE_INVALID_RESOURCE_ID = 3;
  RESOURCE_FAILURE_CODE_INVALID_CLIENT_ID = 4;
  RESOURCE_FAILURE_CODE_RESOURCE_OR_CLIENT_RELEASED = 5;
}

// ResourceFailure carries a stable recovery code and a diagnostic message.
message ResourceFailure {
  ResourceFailureCode code = 1;
  string message = 2;
}

// ResourceRpcPacket negotiates a resource and carries existing SRPC data frames.
message ResourceRpcPacket {
  oneof body {
    // Init selects the resource before any data is sent.
    ResourceRpcInit init = 1;
    // Ack reports whether the server accepted the route.
    ResourceRpcAck ack = 2;
    // Data carries an SRPC packet after the route acknowledgement.
    bytes data = 3;
    // Abandon releases this route's published children that remain unadopted.
    ResourceRpcAbandon abandon = 4;
  }
}

// ResourceRpcInit selects a resource opened by ResourceClient or ResourceAttach.
message ResourceRpcInit {
  uint32 resource_id = 1;
}

// ResourceRpcAck accepts the route when failure is absent.
message ResourceRpcAck {
  ResourceFailure failure = 1;
}

// ResourceRpcAbandon reports that a unary caller failed to receive its result.
// The server releases only children still pending adoption, even after the
// invoked handler has returned. Closing a route alone does not abandon it.
message ResourceRpcAbandon {
}

// ResourceClientRequest is a control packet for ResourceClient.
message ResourceClientRequest {
  reserved 1;
  reserved "supports_resource_adoption_ack";

  // ControlId orders every lifecycle control within one immutable generation.
  // Init uses zero; every later control increments the identifier by one.
  uint32 control_id = 5;

  oneof body {
    // Init starts a new client generation.
    ResourceClientInitRequest init = 2;
    // Adopt detaches a pending child from its parent.
    ResourceClientAdopt adopt = 3;
    // Release releases a resource and its pending descendants.
    ResourceClientRelease release = 4;
  }
}

// ResourceClientInitRequest is sent first on every ResourceClient stream.
message ResourceClientInitRequest {
}

// ResourceClientAdopt adopts a pending resource.
message ResourceClientAdopt {
  // ResourceId identifies the pending resource to adopt.
  uint32 resource_id = 1;
}

// ResourceClientRelease releases a resource and its pending descendants.
message ResourceClientRelease {
  // ResourceId identifies the resource to release.
  uint32 resource_id = 1;
}

// ResourceClientResponse contains a server-client message for a ResourceClient request.
message ResourceClientResponse {
  reserved 3;
  reserved "client_error";

  // Body is the body of the event.
  oneof body {
    // Init contains the initialization message for ResourceClient.
    // This is the first message sent on the stream and is only sent once.
    ResourceClientInit init = 1;
    // ResourceReleased is returned if a resource was released by the server.
    ResourceReleasedResponse resource_released = 2;
    // ControlAck confirms that one lifecycle control and its callbacks completed.
    ResourceClientControlAck control_ack = 4;
  }
}

// ResourceClientControlAck confirms a lifecycle control completed.
message ResourceClientControlAck {
  // ControlId matches ResourceClientRequest.control_id.
  uint32 control_id = 1;
}

// ResourceReleasedResponse is a message indicating a resource was released.
message ResourceReleasedResponse {
  // ResourceId is the ID of the resource that was released.
  uint32 resource_id = 1;
}

// ResourceClientInit is the initialization response to ResourceClient.
message ResourceClientInit {
  // ClientHandleId is the handle identifier for the client.
  uint32 client_handle_id = 1;
  // RootResourceId is the ID of the root resource for this client.
  uint32 root_resource_id = 2;
}

// ResourceAttachRequest is a client-to-server message on the ResourceAttach stream.
message ResourceAttachRequest {
  // Body is the body of the request.
  oneof body {
    // Init is the session initialization message.
    ResourceAttachInit init = 1;
    // Add registers a new resource on the session.
    ResourceAttachAdd add = 2;
    // Detach withdraws a previously added resource.
    ResourceAttachDetach detach = 3;
    // MuxData carries yamux multiplexer frames after handshake.
    bytes mux_data = 4;
  }
}

// ResourceAttachResponse is a server-to-client message on the ResourceAttach stream.
message ResourceAttachResponse {
  // Body is the body of the response.
  oneof body {
    // Ack is the session acknowledgment.
    ResourceAttachAck ack = 1;
    // AddAck confirms a resource was added.
    ResourceAttachAddAck add_ack = 2;
    // DetachAck confirms a resource was detached.
    ResourceAttachDetachAck detach_ack = 3;
    // MuxData carries yamux multiplexer frames after handshake.
    bytes mux_data = 4;
  }
}

// ResourceAttachInit is sent by the client to initiate a session.
message ResourceAttachInit {
  // ClientHandleId identifies the owning client session.
  uint32 client_handle_id = 1;
}

// ResourceAttachAck is sent by the server to confirm the session.
message ResourceAttachAck {
  // Failure is set if the session was rejected.
  ResourceFailure failure = 1;
}

// ResourceAttachAdd is sent by the client to register a resource.
message ResourceAttachAdd {
  // AttachId is a client-chosen correlation ID.
  uint32 attach_id = 1;
  // Label is an informational description of the attached resource.
  string label = 2;
}

// ResourceAttachAddAck is sent by the server to confirm a resource was added.
message ResourceAttachAddAck {
  // AttachId echoes the client-chosen correlation ID.
  uint32 attach_id = 1;
  // Failure is set if the add was rejected.
  ResourceFailure failure = 2;
  // ResourceId is the server-assigned ID for the attached resource.
  uint32 resource_id = 3;
}

// ResourceAttachDetach is sent by the client to withdraw a resource.
message ResourceAttachDetach {
  // ResourceId is the server-assigned ID to detach.
  uint32 resource_id = 1;
}

// ResourceAttachDetachAck is sent by the server to confirm a resource was detached.
message ResourceAttachDetachAck {
  // ResourceId confirms which resource was detached.
  uint32 resource_id = 1;
}