chat/api/chat.api

syntax = "v1"

info (
	title:        "GaoBinYou"
	desc:         "this service will manager chat services"
	version:      "0.0.1"
	contactName:  "daniel wang"
	contactEmail: "igs170911@gmail.com"
	consumes:     "application/json"
	produces:     "application/json"
	schemes:      "http"
	host:         "127.0.0.1:8091"
)

type BaseReq {}

type BaseResp {}

type BaseResponse {
	Code    string      `json:"code"` // 狀態碼
	Message string      `json:"message"` // 訊息
	Data    interface{} `json:"data,omitempty"` // 資料
	Error   interface{} `json:"error,omitempty"` // 可選的錯誤信息
}

type AuthHeader {
	Authorization string `header:"Authorization" binding:"required"`
}

type AnonLoginReq {
	Name string `json:"name" required:"required"`
}

type AnonLoginResp {
	UID             string `json:"uid"`
	Token           string `json:"token"`
	CentrifugoToken string `json:"centrifugo_token"` // Centrifugo WebSocket 連線用的 token
	RefreshToken    string `json:"refresh_token"`
	ExpireAt        int64  `json:"expire_at"`
}

type RefreshTokenReq {
	Token string `json:"token"` // 舊的 token（可以是已過期的）
}

type SendMessageReq {
	AuthHeader
	RoomID      string `path:"room_id"`
	Content     string `json:"content"`
	ClientMsgID string `json:"client_msg_id"`
}

type Message {
	MessageID string `json:"message_id"`
	UID       string `json:"uid"`
	Content   string `json:"content"`
	Timestamp int64  `json:"timestamp"`
}

type ListMessageReq {
	AuthHeader
	RoomID    string `path:"room_id"`
	PageSize  int64  `form:"page_size,default=20"`
	PageIndex int64  `form:"page_index,default=1"`
}

type Pagination {
	Total      int64 `json:"total,example=100"`
	Page       int64 `json:"page,example=1"`
	PageSize   int64 `json:"pageSize,example=10"`
	TotalPages int64 `json:"totalPages,example=10"`
}

type ListMessageResp {
	Pager Pagination `json:"pager"`
	Data  []Message  `json:"data"`
}

// 加入配對池
type MatchJoinReq {
	AuthHeader
}

type MatchJoinResp {
	Status string `json:"status"` // waiting | matched
}

// 查詢配對結果（Polling 版，最快能上）
type MatchStatusResp {
	Status string `json:"status"` // waiting | matched
	RoomID string `json:"room_id,omitempty"`
}

@server (
	group:   chat
	prefix:  /api/v1
	schemes: https
	timeout: 10s
)
service chat-api {
	@doc (
		summary:     "匿名登入"
		description: "拿到匿名的token使得，確認聊天的身分"
	)
	/*
		@respdoc-200 (AnonLoginResp)
		@respdoc-400 (BaseResponse) "請求參數格式錯誤"
		@respdoc-500 (BaseResponse) // 伺服器內部錯誤
	*/
	@handler AnonLogin
	post /auth/anon (AnonLoginReq) returns (AnonLoginResp)

	@doc (
		summary:     "刷新 Token"
		description: "使用現有的 token 來刷新，同時更新 API token 和 Centrifugo token"
	)
	/*
		@respdoc-200 (AnonLoginResp) "返回新的 token"
		@respdoc-400 (BaseResponse) "請求參數格式錯誤"
		@respdoc-401 (BaseResponse) "Token 無效或已過期"
		@respdoc-500 (BaseResponse) // 伺服器內部錯誤
	*/
	@handler RefreshToken
	post /auth/refresh (RefreshTokenReq) returns (AnonLoginResp)
}

@server (
	group:      chat
	prefix:     /api/v1
	schemes:    https
	timeout:    10s
	middleware: AnonMiddleware // 所有此 group 的路由都需要經過 JWT 驗證
)
service chat-api {
	@doc (
		summary:     "傳送訊息"
		description: "傳送訊息"
	)
	/*
		@respdoc-201
		@respdoc-400 (BaseResponse) "請求參數格式錯誤"
		@respdoc-401 (BaseResponse) "未授權或 Token 無效"
		@respdoc-500 (BaseResponse) // 伺服器內部錯誤
	*/
	@handler SendMessage
	post /rooms/:room_id/messages (SendMessageReq) returns (BaseResp)

	@doc (
		summary:     "取得訊息"
		description: "取得訊息"
	)
	/*
		@respdoc-200  (ListMessageResp) "取得聊天訊息"
		@respdoc-400 (BaseResponse) "請求參數格式錯誤"
		@respdoc-401 (BaseResponse) "未授權或 Token 無效"
		@respdoc-500 (BaseResponse) // 伺服器內部錯誤
	*/
	@handler ListMessages
	get /rooms/:room_id/messages (ListMessageReq) returns (ListMessageResp)

	@doc (
		summary:     "加入等待序列"
		description: "加入等待序列"
	)
	/*
		@respdoc-201  (MatchJoinResp) ""
		@respdoc-400 (BaseResponse) "請求參數格式錯誤"
		@respdoc-401 (BaseResponse) "未授權或 Token 無效"
		@respdoc-500 (BaseResponse) // 伺服器內部錯誤
	*/
	@handler MatchJoin
	post /matchmaking/join (MatchJoinReq) returns (MatchJoinResp)

	@doc (
		summary:     "取得房間資訊"
		description: "取得房間資訊"
	)
	/*
		@respdoc-201  (MatchStatusResp) "取得房間資訊"
		@respdoc-400 (BaseResponse) "請求參數格式錯誤"
		@respdoc-401 (BaseResponse) "未授權或 Token 無效"
		@respdoc-500 (BaseResponse) // 伺服器內部錯誤
	*/
	@handler MatchStatus
	get /matchmaking/status (MatchJoinReq) returns (MatchStatusResp)
}