// Package rps is an example of veyron service for playing the game of
// Rock-Paper-Scissors. (http://en.wikipedia.org/wiki/Rock-paper-scissors)
//
// There are three different roles in the game:
//
// 1. Judge: A judge enforces the rules of the game and decides who
//    the winner is. At the end of the game, the judge reports the
//    final score to all the score keepers.
//
// 2. Player: A player can ask a judge to start a new game, it can
//    challenge another player, and it can play a game.
//
// 3. ScoreKeeper: A score keeper receives the final score for a game
//    after it ended.
package rps

// TODO(ashankar,rthellend): This services doesn't really need "tagged" ACLs.
// It can use the simpler access.ACL as an Authorizer and do away with tags
// on methods and the heavier-weight "TaggedACLAuthorizer". Switch to that?
import "v.io/core/veyron2/services/security/access"

type RockPaperScissors interface {
  Judge
  Player
  ScoreKeeper
}

type Judge interface {
  // CreateGame creates a new game with the given game options and returns a game
  // identifier that can be used by the players to join the game.
  CreateGame(Opts GameOptions) (GameID | error) {access.Admin}
  // Play lets a player join an existing game and play.
  Play(ID GameID) stream<PlayerAction,JudgeAction> (PlayResult | error) {access.Admin}
}

// A GameID is used to uniquely identify a game within one Judge.
type GameID struct {
  ID string
}

// GameOptions specifies the parameters of a game.
type GameOptions struct {
  NumRounds int32        // The number of rounds that a player must win to win the game.
  GameType  GameTypeTag  // The type of game to play: Classic or LizardSpock.
}

type GameTypeTag byte
const (
  Classic     = GameTypeTag(0)  // Rock-Paper-Scissors
  LizardSpock = GameTypeTag(1)  // Rock-Paper-Scissors-Lizard-Spock
)

type PlayerAction struct {
  Move string  // The move that the player wants to make.
  Quit bool    // Whether the player wants to quit the game.
}

type JudgeAction struct {
  PlayerNum    int32      // The player's number.
  OpponentName string     // The name of the opponent.
  MoveOptions  []string   // A list of allowed moves that the player must choose from. Not always present.
  RoundResult  Round      // The result of the previous round. Not always present.
  Score        ScoreCard  // The result of the game. Not always present.
}

// Round represents the state of a round.
type Round struct {
  Moves       [2]string  // Each player's move.
  Comment     string     // A text comment from judge about the round.
  Winner      WinnerTag  // Who won the round.
  StartTimeNS int64      // The time at which the round started.
  EndTimeNS   int64      // The time at which the round ended.
}

// WinnerTag is a type used to indicate whether a round or a game was a draw,
// was won by player 1 or was won by player 2.
type WinnerTag byte
const (
  Draw    = WinnerTag(0)
  Player1 = WinnerTag(1)
  Player2 = WinnerTag(2)
)

// PlayResult is the value returned by the Play method. It indicates the outcome of the game.
type PlayResult struct {
  YouWon bool  // True if the player receiving the result won the game.
}

// Player can receive challenges from other players.
type Player interface {
  // Challenge is used by other players to challenge this player to a game. If
  // the challenge is accepted, the method returns nil.
  Challenge(Address string, ID GameID, Opts GameOptions) error {access.Admin}
}

// ScoreKeeper receives the outcome of games from Judges.
type ScoreKeeper interface {
  Record(Score ScoreCard) error {access.Admin}
}

type ScoreCard struct {
  Opts        GameOptions // The game options.
  Judge       string      // The name of the judge.
  Players     []string    // The name of the players.
  Rounds      []Round     // The outcome of each round.
  StartTimeNS int64       // The time at which the game started.
  EndTimeNS   int64       // The time at which the game ended.
  Winner      WinnerTag   // Who won the game.
}