jam-cloud/pb/src/client_container.proto

// adding a new message:
// within ClientMessage block, 
//     create a new field in the enum Type section (100s are meant to be normal messages; 1000s are meant to be errors).  It will have new field number X
//     create a optional message of the same name (but lower-case!  the json code requires this), and use the same field number X.
// then at bottom of the file (or wherever; just outside any existing blocks), add your message definition.

package jampb;

message ClientMessage {
    enum Type { 
        LOGIN = 100;
        LOGIN_ACK = 105;
        LOGIN_MUSIC_SESSION = 110; 
        LOGIN_MUSIC_SESSION_ACK = 115;
        LEAVE_MUSIC_SESSION = 120;
        LEAVE_MUSIC_SESSION_ACK = 125;
        HEARTBEAT = 130;
        HEARTBEAT_ACK = 135;

        // friend notifications
        FRIEND_UPDATE = 140;
        FRIEND_REQUEST = 145;
        FRIEND_REQUEST_ACCEPTED = 150;
        FRIEND_SESSION_JOIN = 155;
        NEW_USER_FOLLOWER = 160;
        NEW_BAND_FOLLOWER = 161;

        // session invitations
        SESSION_INVITATION = 165;
        SESSION_ENDED = 170;
        JOIN_REQUEST = 175;
        JOIN_REQUEST_APPROVED = 180;
        JOIN_REQUEST_REJECTED = 185;
        SESSION_JOIN = 190;
        SESSION_DEPART = 195;
        MUSICIAN_SESSION_JOIN = 196;

        // recording notifications
        MUSICIAN_RECORDING_SAVED = 200;
        BAND_RECORDING_SAVED = 205;
        RECORDING_STARTED = 210;
        RECORDING_ENDED = 215;
        RECORDING_MASTER_MIX_COMPLETE = 220;
        DOWNLOAD_AVAILABLE = 221;

        // band notifications
        BAND_INVITATION = 225;
        BAND_INVITATION_ACCEPTED = 230;
        BAND_SESSION_JOIN = 235;
        
        MUSICIAN_SESSION_FRESH = 240;
        MUSICIAN_SESSION_STALE = 245;


        // icecast notifications
        SOURCE_UP_REQUESTED = 250;
        SOURCE_DOWN_REQUESTED = 255;
        
        TEST_SESSION_MESSAGE = 295;

        PING_REQUEST = 300;
        PING_ACK     = 305;
        PEER_MESSAGE  = 310;
        TEST_CLIENT_MESSAGE = 315;

        SERVER_BAD_STATE_RECOVERED = 900;

        SERVER_GENERIC_ERROR = 1000;
        SERVER_REJECTION_ERROR = 1005;
        SERVER_PERMISSION_ERROR = 1010;
        SERVER_BAD_STATE_ERROR = 1015;
    }

    // Identifies which inner message is filled in
    required Type type = 1;
    required string route_to = 2;
    optional string from = 3;
    optional string message_id = 4;
    optional string in_reply_to = 5;
    
    // One of the following messages can be populated:

    // Client-Server messages (to/from)
    optional Login                      login = 100; // to server
    optional LoginAck                   login_ack = 105; // from server
    optional LoginMusicSession          login_music_session = 110; // to server
    optional LoginMusicSessionAck       login_music_session_ack = 115; // from server
    optional LeaveMusicSession          leave_music_session = 120;
    optional LeaveMusicSessionAck       leave_music_session_ack = 125;
    optional Heartbeat                  heartbeat = 130;
    optional HeartbeatAck               heartbeat_ack = 135;

    // friend notifications
    optional FriendUpdate               friend_update = 140; // from server to all friends of user
    optional FriendRequest              friend_request = 145;
    optional FriendRequestAccepted      friend_request_accepted = 150;
    optional NewUserFollower            new_user_follower = 160;
    optional NewBandFollower            new_band_follower = 161;
    
    // session invitations
    optional SessionInvitation          session_invitation = 165; // from server to user
    optional SessionEnded               session_ended = 170;
    optional JoinRequest                join_request = 175;
    optional JoinRequestApproved        join_request_approved = 180;
    optional JoinRequestRejected        join_request_rejected = 185;
    optional SessionJoin                session_join = 190;
    optional SessionDepart              session_depart = 195;
    optional MusicianSessionJoin        musician_session_join = 196;
    optional BandSessionJoin            band_session_join = 197;

    // recording notifications
    optional MusicianRecordingSaved     musician_recording_saved = 200;
    optional BandRecordingSaved         band_recording_saved = 205;
    optional RecordingStarted           recording_started = 210;
    optional RecordingEnded             recording_ended = 215;
    optional RecordingMasterMixComplete recording_master_mix_complete = 220;
    optional DownloadAvailable          download_available = 221;
    
    // band notifications
    optional BandInvitation             band_invitation = 225;
    optional BandInvitationAccepted     band_invitation_accepted = 230;

    optional MusicianSessionFresh       musician_session_fresh = 240;
    optional MusicianSessionStale       musician_session_stale = 245;

    // icecast notifications
    optional SourceUpRequested          source_up_requested = 250;
    optional SourceDownRequested        source_down_requested = 255;

    // Client-Session messages (to/from)  
    optional TestSessionMessage     test_session_message = 295;

    // Client-Client messages (to/from)
    optional PingRequest        ping_request = 300;
    optional PingAck            ping_ack = 305;
    optional PeerMessage        peer_message = 310;
    optional TestClientMessage  test_client_message = 315;

    // Server-to-Client special messages
    optional ServerBadStateRecovered server_bad_state_recovered = 900;

    // Server-to-Client errors 
    optional ServerGenericError server_generic_error = 1000;
    optional ServerRejectionError server_rejection_error = 1005;
    optional ServerPermissionError server_permission_error = 1010;
    optional ServerBadStateError server_bad_state_error = 1015;
}

// route_to: server
// sent from client to server to associate the connection with a user
// either supply a username/password, or just supply token
// if successful, a LoginAck is sent.
// if errored, a GenericServerError is sent and the connection is closed.
message Login {
    optional string username = 1; // username... could be email.  need to wait for prod requirements
    optional string password = 2; // a password
    optional string token = 3; // a token/cookie from previous successful login attempt or from 'token' field in .music file
    optional string client_id = 4; // if supplied, the server will accept this client_id as the unique Id of this client instance
    optional string reconnect_music_session_id = 5; // if supplied, the server will attempt to log the client into this session (designed for reconnect scenarios while in-session)

}

// route_to: client
// sent from server to client to let the client know the login was successful,
// and to also show the IP address of the client as seen by the server.
message LoginAck {
    optional string public_ip = 1;
    optional string client_id = 2; // a new client_id if none is supplied in Login, or just the original client_id echoed back
    optional string token = 3; // the remember me token.  This is useful if you logged in with username/password (otherwise it's just 'token' echoed back)
    optional int32  heartbeat_interval = 4; // set your heartbeat interval to this value
    optional string music_session_id = 5; // the music session that the user was in very recently (likely due to dropped connection)
    optional bool   reconnected = 6; // if reconnect_music_session_id is specified, and the server could log the user into that session, then true is returned. 
    optional string user_id = 7; // the database user id
}

// route_to: server
// send from client to server to log in to a music session and be 'present'.
// if successful, a LoginMusicSessionAck is sent with error = false, and Client-Session messages will be passed 
// directly from client to all other client. Also, the server will generate a 'UserJoinedMusicSession' message
// and send it to all other users to let the others know the user is here.
// if errored, a LoginMusicSessionAck is sent with error = true.
message LoginMusicSession {
   optional string music_session = 1; 
}

// route_to: client
// error = true if the LoginMusicSession command failed.
message LoginMusicSessionAck {
    optional bool error = 1;
    optional string error_reason = 2;
}

// route_to: server
// send from client to server to leave a previously joined music session
message LeaveMusicSession {
    optional string music_session = 1;
}

// route_to: client
// error = true if the session didn't exist, but otherwise this is intended to always work barring server unrecoverable errors
message LeaveMusicSessionAck {
    optional bool error = 1;
    optional string error_reason = 2;
}

message FriendUpdate {
    optional string user_id = 1;
    optional string photo_url = 2;
    optional bool online = 3;
    optional string msg = 4;
}

message FriendRequest {
    optional string friend_request_id = 1;
    optional string photo_url = 2;
    optional string msg = 3;
    optional string notification_id = 4;
    optional string created_at = 5;
}

message FriendRequestAccepted {
    optional string photo_url = 1;
    optional string msg = 2;
    optional string notification_id = 3;
    optional string created_at = 4;
}

message NewUserFollower {
    optional string photo_url = 1;
    optional string msg = 2;
    optional string notification_id = 3;
    optional string created_at = 4;
}

message NewBandFollower {
    optional string photo_url = 1;
    optional string msg = 2;
    optional string notification_id = 3;
    optional string created_at = 4;
}

message SessionInvitation {
    optional string session_id = 1;
    optional string msg = 2;
    optional string notification_id = 3;
    optional string created_at = 4;
}

message SessionEnded {
    
}

message JoinRequest {
    optional string join_request_id = 1;
    optional string session_id = 2;
    optional string photo_url = 3;
    optional string msg = 4;
    optional string notification_id = 5;
    optional string created_at = 6;
}

message JoinRequestApproved {
    optional string join_request_id = 1;
    optional string session_id = 2;
    optional string photo_url = 3;
    optional string msg = 4;
    optional string notification_id = 5;
    optional string created_at = 6;
}

message JoinRequestRejected {
    optional string invitation_id = 1;
    optional string session_id = 2;
    optional string photo_url = 3;
    optional string msg = 4;
    optional string notification_id = 5;
    optional string created_at = 6;
}

message SessionJoin {
    optional string session_id = 1;
    optional string photo_url = 2;
    optional string msg = 3;
}

message SessionDepart {
    optional string session_id = 1;
    optional string photo_url = 2;
    optional string msg = 3;
    optional string recording_id = 4;
}

message MusicianSessionJoin {
    optional string session_id = 1;
    optional string photo_url = 2;
    optional string msg = 3;
    optional string notification_id = 4;
    optional string created_at = 5;
}

message BandSessionJoin {
    optional string session_id = 1;
    optional string photo_url = 2;
    optional string msg = 3;
    optional string notification_id = 4;
    optional string created_at = 5;
}

message MusicianRecordingSaved {
    optional string recording_id = 1;
    optional string photo_url = 2;
    optional string msg = 3;
    optional string notification_id = 4;
    optional string created_at = 5;
}

message BandRecordingSaved {
    optional string recording_id = 1;
    optional string photo_url = 2;
    optional string msg = 3;
    optional string notification_id = 4;
    optional string created_at = 5;
}

message RecordingStarted {
    optional string photo_url = 1;
    optional string msg = 2;
}

message RecordingEnded {
    optional string photo_url = 1;
    optional string msg = 2;
}

message RecordingMasterMixComplete {
    optional string recording_id = 1;
    optional string band_id = 2;
    optional string msg = 3;
    optional string notification_id = 4;
    optional string created_at = 5;
}

message DownloadAvailable {

}

message BandInvitation {
    optional string band_invitation_id = 1;
    optional string band_id = 2;
    optional string photo_url = 3;
    optional string msg = 4;
    optional string notification_id = 5;
    optional string created_at = 6;
}

message BandInvitationAccepted {
    optional string band_invitation_id = 1;
    optional string photo_url = 2;
    optional string msg = 3;
    optional string notification_id = 4;
    optional string created_at = 5;
}

// route_to: client:
// sent by server to let the rest of the participants know a client has become active again after going stale 
message MusicianSessionFresh {
    optional string session_id = 1; // the session ID
    optional string user_id = 2; // this is the user_id and can be used for user unicast messages
    optional string username = 3; // meant to be a display name
    optional string photo_url = 4;
}

// route_to: client:
// sent by server to let the rest of the participants know a user has gone stale (websocket connection dropped) 
message MusicianSessionStale {
    optional string session_id = 1; // the session ID
    optional string user_id = 2; // this is the user_id and can be used for user unicast messages
    optional string username = 3; // meant to be a display name
    optional string photo_url = 4;
}

message SourceUpRequested {

}

message SourceDownRequested {

}

// route_to: session
// a test message used by ruby-client currently.  just gives way to send out to rest of session
message TestSessionMessage {
    optional string msg = 1;
}

// route_to: client:[CLIENT_ID]
// asks a client to begin a ping session
message PingRequest {
    
}

// route_to: client:[CLIENT_ID]
// tells a client to begin pinging a session
message PingAck {

}

// route_to: client:[CLIENT_ID]
// generic message between clients
message PeerMessage {
    optional string message = 1;
}

// route_to: client:[CLIENT_ID]
// a test message used by ruby-client currently.  just gives a way to send directly to another client
message TestClientMessage {
    optional string msg = 1;
}

// route_to: server
// sent from client to server periodically to let server track if the client is truly alive and avoid TCP timeout scenarios
// the server will send a HeartbeatAck in response to this
message Heartbeat {
    
}

// target: client
// sent from server to client in response to a Heartbeat
message HeartbeatAck {
}

// route_to: client
// this should follow a ServerBadStateError in the case that the 
// websocket gateway recovers from whatever ailed it
message ServerBadStateRecovered {
}

// route_to: client
// this indicates unhandled error on server
// if you receive this, your connection will close after.
// but gives the client a chance to know why.
message ServerGenericError {
    optional string error_msg = 1;
}

// route_to: client
// this indicates the client did something wrong, and the server is mad enough to close connection.
// if you receive this, your connection will close after.
// but gives the client a chance to know why.
message ServerRejectionError {
    optional string error_msg = 1;
}

// route_to: client
// this indicates that the client doesn't have permission to ask the command
// your connection is not closed if this message occurs
message ServerPermissionError {
    optional string error_msg = 1;
}

// route_to: client
// this indicates that the server is in a bad state, but could recover later, and is unable to process the request
// your connection is not closed if this message occurs
message ServerBadStateError {
    optional string error_msg = 1;
}