TT Client Library 1.0.0
C++ library for Tandem Tales clients.
Loading...
Searching...
No Matches
Client.h
1#pragma once
2
3#include <string>
4#include <tt/Role.h>
5#include <openssl/ssl.h>
6#include <openssl/err.h>
7#include <thread>
8#include <tt/world/World.h>
9#include <tt/io/Stop.h>
10#include <tt/world/Status.h>
11#include <tt/world/Turn.h>
12#include <tt/io/Connect.h>
13#include <tt/world/State.h>
14#include <tt/Role.h>
15#include <tt/util/BlockingQueue.h>
16#include <atomic>
17#include <tt/ExternalAPI.h>
18
19#ifndef CLIENT_H
20#define CLIENT_H
21
22namespace tt {
23 // forward declarations to avoid circular inheritance
24 class ClientFactory;
25 class Join;
26 class Message;
27
51 class Client {
52 public:
60 const static std::string ENVIRONMENT_VARIABLE_PASSWORD;
61
69 const static std::string ENVIRONMENT_VARIABLE_API_KEY;
70
75 const static std::string DEFAULT_URL;
76
81 const static int DEFAULT_PORT;
82
85
104 Client(const std::string& name, const std::string& password, const std::string& world, Role role, const std::string& partner, const char* key, const std::string& url, int port);
105
122 Client(const std::string& name, const std::string& world, Role role, const std::string& partner, const std::string& url, int port);
123
137 Client(const std::string& name, const std::string& world, Role role, const std::string& partner);
138
150 Client(const std::string& name, const std::string& world, Role role);
151
159 Client(const std::string& name);
160
166 virtual std::string toString() const;
167
173 const std::string& getName() const;
174
184 const std::string& getWorldName() const;
185
194 Role getRole() const;
195
205 const std::string& getPartner() const;
206
214 const World* getWorld();
215
226 std::vector<const Turn *> getHistory() const;
227
234 const State * getState() const;
235
244 std::vector<const Turn *> getChoices() const;
245
253 const std::string& getSession();
254
301 std::string execute();
303 std::string execute(ClientFactory* factory);
305
323 SSL* connect(const std::string& url, int port);
324
325 virtual ~Client();
326
339 void sendMessage(const tt::Message& m);
340
341
348 void close();
349
350 friend std::ostream& operator<<(std::ostream& os, const Client& a);
351
352 protected:
359 void setName(const std::string& name);
360
367 void setPassword(const std::string& password);
368
375 void setWorldName(const std::string& world);
376
383 void setRole(Role role);
384
391 void setPartner(const std::string& partner);
392
405 virtual void onConnect(const Connect* connect){
406 // This method is meant to be overridden.
407 };
408
420 virtual void onStart(const World* world, Role role, const State* initial) {
421 // This method is meant to be overridden.
422 }
423
436 virtual void onUpdate(const Status* status) {
437 // This method is meant to be overridden.
438 }
439
454 virtual int onChoice(const Status* status) = 0;
455
466 virtual void onEnd(const Ending *ending) {
467 // This method is meant to be overridden.
468 }
469
481 virtual void onStop(const std::string& message){
482 // This method is meant to be overridden.
483 };
484
497 virtual void onClose(){
498 // This method is meant to be overridden.
499 };
500
510 virtual void onDisconnect(){
511 // This method is meant to be overridden.
512 };
513
522 virtual void onWarning(const std::string& message);
523
535 virtual void onError(const std::string& message);
536
545 std::unique_ptr<Message> receiveAny();
546
547 template <typename T>
559 std::unique_ptr<T> receive();
560
561 private:
563 std::string url;
564
566 int port;
567
572 std::unique_ptr<Join> join;
573
575 SSL* ssl = nullptr;
576 SSL_CTX* ctx = nullptr;
577 int sock = -1;
578
580 std::thread receiveThread_;
581 std::atomic<bool> running_{true};
582
584 bool joined = false;
585
587 std::unique_ptr<World> world = nullptr;
588
590 Role role = Role::NONE;
591
593 std::unique_ptr<Status> status = nullptr;
594
596 std::vector<const Turn *> choices;
597
599 std::unique_ptr<Stop> stop = nullptr;
600
602 std::string session = "";
603
613 void failIfJoined(const std::string& property);
614
626 template <typename T>
627 static const T* failIfNotStarted(const T* object, const std::string& description);
628
640 template <typename T>
641 static const T* failIfNotStarted(const std::unique_ptr<T>& object, const std::string& description);
642
652 void sendMessage(const std::string& s);
653
662 void receiveLoop();
663
664 /* A blocking queue used by {@link #execute()} to wait for messages */
665 BlockingQueue<std::unique_ptr<Message>> messageQueue_;
666
674 std::unique_ptr<Message> processMessage(const char* data, int length);
675
676 /* A buffer used by {@link #receiveLoop} to store messages if they are received in parts*/
677 std::string recvBuffer_;
678
680 bool receivedStop = false;
681
683 std::mutex closeMutex_;
684
685 };
686
693 std::ostream& operator<<(std::ostream& os, const Client& a);
694}
695
696#endif
A client factory continuously creates clients to connect to a server and is useful for deploying auto...
Definition ClientFactory.h:46
A client connects to a server to find a partner and play a role in a storytelling session.
Definition Client.h:51
virtual void onError(const std::string &message)
This method is called if the server reports an error to this client.
Definition Client.cpp:419
void setRole(Role role)
Sets the role this client wants to play in its session.
Definition Client.cpp:446
virtual void onDisconnect()
If the client ever established its connection to the server, this method is called once right before ...
Definition Client.h:510
std::unique_ptr< T > receive()
Waits for a Message of a specified type to be received.
Definition Client.cpp:573
virtual void onClose()
This method is called once if the client was closed, if it was interrupted, or if the socket was disc...
Definition Client.h:497
std::vector< const Turn * > getChoices() const
If it is currently this client's turn to act, this method returns the list of turns they can take nex...
Definition Client.cpp:458
std::unique_ptr< Message > receiveAny()
Waits for a Message of any type to be received.
Definition Client.cpp:562
std::string execute()
Definition Client.cpp:126
void setPartner(const std::string &partner)
Sets the name of the partner this client wants to play in its session.
Definition Client.cpp:452
static const std::string DEFAULT_URL
The default URL the client will attempt to connect to if one is not explicitly provided in the constr...
Definition Client.h:75
friend std::ostream & operator<<(std::ostream &os, const Client &a)
Override stream insertion operator to allow printing the Client class.
std::vector< const Turn * > getHistory() const
Returns the list of all turns that have been taken so far in this client's session that this client h...
Definition Client.cpp:116
void setWorldName(const std::string &world)
Sets the name of the story world this client wants to play in.
Definition Client.cpp:440
virtual int onChoice(const Status *status)=0
This method is called each time it is this client's turn to make a choice in the story.
virtual void onUpdate(const Status *status)
This method is called each time the story world changes as a result of a turn the client observes.
Definition Client.h:436
virtual void onEnd(const Ending *ending)
This method is called once if the story reaches one of its pre-defined endings.
Definition Client.h:466
void sendMessage(const tt::Message &m)
This method sends a message to the server.
Definition Client.cpp:364
static const int DEFAULT_PORT
The default network port the client will attempt to connect to if one is not explicitly provided in t...
Definition Client.h:81
void setName(const std::string &name)
Sets the name this client will use.
Definition Client.cpp:428
const std::string & getPartner() const
Returns the name of the partner this client wants to play with.
Definition Client.cpp:106
virtual void onWarning(const std::string &message)
This method is called if this client encounters a problem which does not immediately require it to cl...
Definition Client.cpp:414
const std::string & getName() const
Returns the client's name.
Definition Client.cpp:85
virtual void onStop(const std::string &message)
This method is called once when the client's session ends.
Definition Client.h:481
SSL * connect(const std::string &url, int port)
Establishes a secure socket to the server based on this client's network configuration.
Definition Client.cpp:276
virtual void onConnect(const Connect *connect)
This method is called after the client connects to the server and the server sends the list of availa...
Definition Client.h:405
static const std::string ENVIRONMENT_VARIABLE_PASSWORD
The name of the environment variable where the client expects to find the password this agent will us...
Definition Client.h:60
ExternalAPI external
Used to access external APIs.
Definition Client.h:84
const std::string & getSession()
Returns the ID of this client's session.
Definition Client.cpp:464
static const std::string ENVIRONMENT_VARIABLE_API_KEY
The name of the environment variable where the client expects to find the API key used to authenticat...
Definition Client.h:69
Role getRole() const
Returns the role this client wants to play or is currently playing in its session.
Definition Client.cpp:98
const State * getState() const
Returns the current state of the story world.
Definition Client.cpp:121
Client(const std::string &name, const std::string &password, const std::string &world, Role role, const std::string &partner, const char *key, const std::string &url, int port)
Constructs a client with the given session preferences, password, API key, and network details.
Definition Client.cpp:32
void setPassword(const std::string &password)
Sets the password this client will use.
Definition Client.cpp:434
virtual std::string toString() const
Gives a string representation of this client.
Definition Client.cpp:71
void close()
Definition Client.cpp:530
virtual void onStart(const World *world, Role role, const State *initial)
This method is called once when the client's session starts.
Definition Client.h:420
const World * getWorld()
Returns a const pointer to the story world in which this client's session is taking place.
Definition Client.cpp:111
const std::string & getWorldName() const
Returns the name of the story world this client will play in or is currently playing in.
Definition Client.cpp:90
The connect message is sent from the server to a client as soon as the agent connects to give details...
Definition Connect.h:17
An ending is a signed asset that represents one of several possible ways a story can end.
Definition Ending.h:17
Represents the external API used for text embedding and completion.
Definition ExternalAPI.h:16
The join message is the first message sent from a client to the server to provide the agent's credent...
Definition Join.h:18
A message is information sent to or from a server in JSON format.
Definition Message.h:23
A state is an assignment of values to each variable in a story world.
Definition State.h:18
A status contains the full history of a session in a story world, a description of its current state,...
Definition Status.h:22
A story world is a collection of assets needed for two partners in a session to tell a collaborative ...
Definition World.h:20
Tandem Tales is a platform that enables short, paired storytelling exercises between two agents over ...
Definition Client.h:22
Role
Represents the two roles in a collaborative storytelling session: the Player, who typically controls ...
Definition Role.h:16
@ NONE
No role, used as a "null" value.
Definition Role.h:32
std::ostream & operator<<(std::ostream &os, const Client &a)
Override stream insertion operator to allow printing the Client class.
Definition Client.cpp:556