// CODYlib -*- mode:c++ -*-
// Copyright (C) 2020 Nathan Sidwell, nathan@acm.org
// License: Apache v2.0
#ifndef CODY_HH
#define CODY_HH 1
// If the user specifies this as non-zero, it must be what we expect,
// generally only good for requesting no networking
#if !defined (CODY_NETWORKING)
// Have a known-good list of networking systems
#if defined (__unix__) || defined (__MACH__)
#define CODY_NETWORKING 1
#else
#define CODY_NETWORKING 0
#endif
#if 0 // For testing
#undef CODY_NETWORKING
#define CODY_NETWORKING 0
#endif
#endif
// C++
#include <memory>
#include <string>
#include <vector>
// C
#include <cstddef>
// OS
#include <errno.h>
#include <sys/types.h>
#if CODY_NETWORKING
#include <sys/socket.h>
#endif
namespace Cody {
// Set version to 1, as this is completely incompatible with 0.
// Fortunately both versions 0 and 1 will recognize each other's HELLO
// messages sufficiently to error out
constexpr unsigned Version = 1;
// FIXME: I guess we need a file-handle abstraction here
// Is windows DWORDPTR still?, or should it be FILE *? (ew).
namespace Detail {
// C++11 doesn't have utf8 character literals :(
template<unsigned I>
constexpr char S2C (char const (&s)[I])
{
static_assert (I == 2, "only single octet strings may be converted");
return s[0];
}
/// Internal buffering class. Used to concatenate outgoing messages
/// and Lex incoming ones.
class MessageBuffer
{
std::vector<char> buffer; ///< buffer holding the message
size_t lastBol = 0; ///< location of the most recent Beginning Of
///< Line, or position we've readed when writing
public:
MessageBuffer () = default;
~MessageBuffer () = default;
MessageBuffer (MessageBuffer &&) = default;
MessageBuffer &operator= (MessageBuffer &&) = default;
public:
///
/// Finalize a buffer to be written. No more lines can be added to
/// the buffer. Use before a sequence of Write calls.
void PrepareToWrite ()
{
buffer.push_back (u8"\n"[0]);
lastBol = 0;
}
///
/// Prepare a buffer for reading. Use before a sequence of Read calls.
void PrepareToRead ()
{
buffer.clear ();
lastBol = 0;
}
public:
/// Begin a message line. Use before a sequence of Append and
/// related calls.
void BeginLine ();
/// End a message line. Use after a sequence of Append and related calls.
void EndLine () {}
public:
/// Append a string to the current line. No whitespace is prepended
/// or appended.
///
/// @param str the string to be written
/// @param maybe_quote indicate if there's a possibility the string
/// contains characters that need quoting. Defaults to false.
/// It is always safe to set
/// this true, but that causes an additional scan of the string.
/// @param len The length of the string. If not specified, strlen
/// is used to find the length.
void Append (char const *str, bool maybe_quote = false,
size_t len = ~size_t (0));
///
/// Add whitespace word separator. Multiple adjacent whitespace is fine.
void Space ()
{
Append (Detail::S2C(u8" "));
}
public:
/// Add a word as with Append, but prefixing whitespace to make a
/// separate word
void AppendWord (char const *str, bool maybe_quote = false,
size_t len = ~size_t (0))
{
if (buffer.size () != lastBol)
Space ();
Append (str, maybe_quote, len);
}
/// Add a word as with AppendWord
/// @param str the string to append
/// @param maybe_quote string might need quoting, as for Append
void AppendWord (std::string const &str, bool maybe_quote = false)
{
AppendWord (str.data (), maybe_quote, str.size ());
}
///
/// Add an integral value, prepending a space.
void AppendInteger (unsigned u);
private:
/// Append a literal character.
/// @param c character to append
void Append (char c);
public:
/// Lex the next input line into a vector of words.
/// @param words filled with a vector of lexed strings
/// @result 0 if no errors, an errno value on lexxing error such as
/// there being no next line (ENOENT), or malformed quoting (EINVAL)
int Lex (std::vector<std::string> &words);
public:
/// Append the most-recently lexxed line to a string. May be useful
/// in error messages. The unparsed line is appended -- before any
/// unquoting.
/// If we had c++17 string_view, we'd simply return a view of the
/// line, and leave it to the caller to do any concatenation.
/// @param l string to-which the lexxed line is appended.
void LexedLine (std::string &l);
public:
/// Detect if we have reached the end of the input buffer.
/// I.e. there are no more lines to Lex
/// @result True if at end
bool IsAtEnd () const
{
return lastBol == buffer.size ();
}
public:
/// Read from end point into a read buffer, as with read(2). This will
/// not block , unless FD is blocking, and there is nothing
/// immediately available.
/// @param fd file descriptor to read from. This may be a regular
/// file, pipe or socket.
/// @result on error returns errno. If end of file occurs, returns
/// -1. At end of message returns 0. If there is more needed
/// returns EAGAIN (or possibly EINTR). If the message is
/// malformed, returns EINVAL.
int Read (int fd) noexcept;
public:
/// Write to an end point from a write buffer, as with write(2). As
/// with Read, this will not usually block.
/// @param fd file descriptor to write to. This may be a regular
/// file, pipe or socket.
/// @result on error returns errno.
/// At end of message returns 0. If there is more to write
/// returns EAGAIN (or possibly EINTR).
int Write (int fd) noexcept;
};
///
/// Request codes. Perhaps this should be exposed? These are likely
/// useful to servers that queue requests.
enum RequestCode
{
RC_CONNECT,
RC_MODULE_REPO,
RC_MODULE_EXPORT,
RC_MODULE_IMPORT,
RC_MODULE_COMPILED,
RC_INCLUDE_TRANSLATE,
RC_HWM
};
/// Internal file descriptor tuple. It's used as an anonymous union member.
struct FD
{
int from; ///< Read from this FD
int to; ///< Write to this FD
};
}
// Flags for various requests
enum class Flags : unsigned
{
None,
NameOnly = 1<<0, // Only querying for CMI names, not contents
};
inline Flags operator& (Flags a, Flags b)
{
return Flags (unsigned (a) & unsigned (b));
}
inline Flags operator| (Flags a, Flags b)
{
return Flags (unsigned (a) | unsigned (b));
}
///
/// Response data for a request. Returned by Client's request calls,
/// which return a single Packet. When the connection is Corked, the
/// Uncork call will return a vector of Packets.
class Packet
{
public:
///
/// Packet is a variant structure. These are the possible content types.
enum Category { INTEGER, STRING, VECTOR};
private:
// std:variant is a C++17 thing, so we're doing this ourselves.
union
{
size_t integer; ///< Integral value
std::string string; ///< String value
std::vector<std::string> vector; ///< Vector of string value
};
Category cat : 2; ///< Discriminator
private:
unsigned short code = 0; ///< Packet type
unsigned short request = 0;
public:
Packet (unsigned c, size_t i = 0)
: integer (i), cat (INTEGER), code (c)
{
}
Packet (unsigned c, std::string &&s)
: string (std::move (s)), cat (STRING), code (c)
{
}
Packet (unsigned c, std::string const &s)
: string (s), cat (STRING), code (c)
{
}
Packet (unsigned c, std::vector<std::string> &&v)
: vector (std::move (v)), cat (VECTOR), code (c)
{
}
// No non-move constructor from a vector. You should not be doing
// that.
// Only move constructor and move assignment
Packet (Packet &&t)
{
Create (std::move (t));
}
Packet &operator= (Packet &&t)
{
Destroy ();
Create (std::move (t));
return *this;
}
~Packet ()
{
Destroy ();
}
private:
///
/// Variant move creation from another packet
void Create (Packet &&t);
///
/// Variant destruction
void Destroy ();
public:
///
/// Return the packet type
unsigned GetCode () const
{
return code;
}
///
/// Return the packet type
unsigned GetRequest () const
{
return request;
}
void SetRequest (unsigned r)
{
request = r;
}
///
/// Return the category of the packet's payload
Category GetCategory () const
{
return cat;
}
public:
///
/// Return an integral payload. Undefined if the category is not INTEGER
size_t GetInteger () const
{
return integer;
}
///
/// Return (a reference to) a string payload. Undefined if the
/// category is not STRING
std::string const &GetString () const
{
return string;
}
std::string &GetString ()
{
return string;
}
///
/// Return (a reference to) a constant vector of strings payload.
/// Undefined if the category is not VECTOR
std::vector<std::string> const &GetVector () const
{
return vector;
}
///
/// Return (a reference to) a non-conatant vector of strings payload.
/// Undefined if the category is not VECTOR
std::vector<std::string> &GetVector ()
{
return vector;
}
};
class Server;
///
/// Client-side (compiler) object.
class Client
{
public:
/// Response packet codes
enum PacketCode
{
PC_CORKED, ///< Messages are corked
PC_CONNECT, ///< Packet is integer version
PC_ERROR, ///< Packet is error string
PC_OK,
PC_BOOL,
PC_PATHNAME
};
private:
Detail::MessageBuffer write; ///< Outgoing write buffer
Detail::MessageBuffer read; ///< Incoming read buffer
std::string corked; ///< Queued request tags
union
{
Detail::FD fd; ///< FDs connecting to server
Server *server; ///< Directly connected server
};
bool is_direct = false; ///< Discriminator
bool is_connected = false; /// Connection handshake succesful
private:
Client ();
public:
/// Direct connection constructor.
/// @param s Server to directly connect
Client (Server *s)
: Client ()
{
is_direct = true;
server = s;
}
/// Communication connection constructor
/// @param from file descriptor to read from
/// @param to file descriptor to write to, defaults to from
Client (int from, int to = -1)
: Client ()
{
fd.from = from;
fd.to = to < 0 ? from : to;
}
~Client ();
// We have to provide our own move variants, because of the variant member.
Client (Client &&);
Client &operator= (Client &&);
public:
///
/// Direct connection predicate
bool IsDirect () const
{
return is_direct;
}
///
/// Successful handshake predicate
bool IsConnected () const
{
return is_connected;
}
public:
///
/// Get the read FD
/// @result the FD to read from, -1 if a direct connection
int GetFDRead () const
{
return is_direct ? -1 : fd.from;
}
///
/// Get the write FD
/// @result the FD to write to, -1 if a direct connection
int GetFDWrite () const
{
return is_direct ? -1 : fd.to;
}
///
/// Get the directly-connected server
/// @result the server, or nullptr if a communication connection
Server *GetServer () const
{
return is_direct ? server : nullptr;
}
public:
///
/// Perform connection handshake. All othe requests will result in
/// errors, until handshake is succesful.
/// @param agent compiler identification
/// @param ident compilation identifiation (maybe nullptr)
/// @param alen length of agent string, if known
/// @param ilen length of ident string, if known
/// @result packet indicating success (or deferrment) of the
/// connection, payload is optional flags
Packet Connect (char const *agent, char const *ident,
size_t alen = ~size_t (0), size_t ilen = ~size_t (0));
/// std::string wrapper for connection
/// @param agent compiler identification
/// @param ident compilation identification
Packet Connect (std::string const &agent, std::string const &ident)
{
return Connect (agent.c_str (), ident.c_str (),
agent.size (), ident.size ());
}
public:
/// Request compiler module repository
/// @result packet indicating repo
Packet ModuleRepo ();
public:
/// Inform of compilation of a named module interface or partition,
/// or a header unit
/// @param str module or header-unit
/// @param len name length, if known
/// @result CMI name (or deferrment/error)
Packet ModuleExport (char const *str, Flags flags, size_t len = ~size_t (0));
Packet ModuleExport (char const *str)
{
return ModuleExport (str, Flags::None, ~size_t (0));
}
Packet ModuleExport (std::string const &s, Flags flags = Flags::None)
{
return ModuleExport (s.c_str (), flags, s.size ());
}
public:
/// Importation of a module, partition or header-unit
/// @param str module or header-unit
/// @param len name length, if known
/// @result CMI name (or deferrment/error)
Packet ModuleImport (char const *str, Flags flags, size_t len = ~size_t (0));
Packet ModuleImport (char const *str)
{
return ModuleImport (str, Flags::None, ~size_t (0));
}
Packet ModuleImport (std::string const &s, Flags flags = Flags::None)
{
return ModuleImport (s.c_str (), flags, s.size ());
}
public:
/// Successful compilation of a module interface, partition or
/// header-unit. Must have been preceeded by a ModuleExport
/// request.
/// @param str module or header-unit
/// @param len name length, if known
/// @result OK (or deferment/error)
Packet ModuleCompiled (char const *str, Flags flags, size_t len = ~size_t (0));
Packet ModuleCompiled (char const *str)
{
return ModuleCompiled (str, Flags::None, ~size_t (0));
}
Packet ModuleCompiled (std::string const &s, Flags flags = Flags::None)
{
return ModuleCompiled (s.c_str (), flags, s.size ());
}
/// Include translation query.
/// @param str header unit name
/// @param len name length, if known
/// @result Packet indicating include translation boolean, or CMI
/// name (or deferment/error)
Packet IncludeTranslate (char const *str, Flags flags,
size_t len = ~size_t (0));
Packet IncludeTranslate (char const *str)
{
return IncludeTranslate (str, Flags::None, ~size_t (0));
}
Packet IncludeTranslate (std::string const &s, Flags flags = Flags::None)
{
return IncludeTranslate (s.c_str (), flags, s.size ());
}
public:
/// Cork the connection. All requests are queued up. Each request
/// call will return a PC_CORKED packet.
void Cork ();
/// Uncork the connection. All queued requests are sent to the
/// server, and a block of responses waited for.
/// @result A vector of packets, containing the in-order responses to the
/// queued requests.
std::vector<Packet> Uncork ();
///
/// Indicate corkedness of connection
bool IsCorked () const
{
return !corked.empty ();
}
private:
Packet ProcessResponse (std::vector<std::string> &, unsigned code,
bool isLast);
Packet MaybeRequest (unsigned code);
int CommunicateWithServer ();
};
/// This server-side class is used to resolve requests from one or
/// more clients. You are expected to derive from it and override the
/// virtual functions it provides. The connection resolver may return
/// a different resolved object to service the remainder of the
/// connection -- for instance depending on the compiler that is
/// making the requests.
class Resolver
{
public:
Resolver () = default;
virtual ~Resolver ();
protected:
/// Mapping from a module or header-unit name to a CMI file name.
/// @param module module name
/// @result CMI name
virtual std::string GetCMIName (std::string const &module);
/// Return the CMI file suffix to use
/// @result CMI suffix, a statically allocated string
virtual char const *GetCMISuffix ();
public:
/// When the requests of a directly-connected server are processed,
/// we may want to wait for the requests to complete (for instance a
/// set of subjobs).
/// @param s directly connected server.
virtual void WaitUntilReady (Server *s);
public:
/// Provide an error response.
/// @param s the server to provide the response to.
/// @param msg the error message
virtual void ErrorResponse (Server *s, std::string &&msg);
public:
/// Connection handshake. Provide response to server and return new
/// (or current) resolver, or nullptr.
/// @param s server to provide response to
/// @param version the client's version number
/// @param agent the client agent (compiler identification)
/// @param ident the compilation identification (may be empty)
/// @result nullptr in the case of an error. An error response will
/// be sent. If handing off to another resolver, return that,
/// otherwise this
virtual Resolver *ConnectRequest (Server *s, unsigned version,
std::string &agent, std::string &ident);
public:
// return 0 on ok, ERRNO on failure, -1 on unspecific error
virtual int ModuleRepoRequest (Server *s);
virtual int ModuleExportRequest (Server *s, Flags flags,
std::string &module);
virtual int ModuleImportRequest (Server *s, Flags flags,
std::string &module);
virtual int ModuleCompiledRequest (Server *s, Flags flags,
std::string &module);
virtual int IncludeTranslateRequest (Server *s, Flags flags,
std::string &include);
};
/// This server-side (build system) class handles a single connection
/// to a client. It has 3 states, READING:accumulating a message
/// block froma client, WRITING:writing a message block to a client
/// and PROCESSING:resolving requests. If the server does not spawn
/// jobs to build needed artifacts, the PROCESSING state will be brief.
class Server
{
public:
enum Direction
{
READING, // Server is waiting for completion of a (set of)
// requests from client. The next state will be PROCESSING.
WRITING, // Server is writing a (set of) responses to client.
// The next state will be READING.
PROCESSING // Server is processing client request(s). The next
// state will be WRITING.
};
private:
Detail::MessageBuffer write;
Detail::MessageBuffer read;
Resolver *resolver;
Detail::FD fd;
bool is_connected = false;
Direction direction : 2;
public:
Server (Resolver *r);
Server (Resolver *r, int from, int to = -1)
: Server (r)
{
fd.from = from;
fd.to = to >= 0 ? to : from;
}
~Server ();
Server (Server &&);
Server &operator= (Server &&);
public:
bool IsConnected () const
{
return is_connected;
}
public:
void SetDirection (Direction d)
{
direction = d;
}
public:
Direction GetDirection () const
{
return direction;
}
int GetFDRead () const
{
return fd.from;
}
int GetFDWrite () const
{
return fd.to;
}
Resolver *GetResolver () const
{
return resolver;
}
public:
/// Process requests from a directly-connected client. This is a
/// small wrapper around ProcessRequests, with some buffer swapping
/// for communication. It is expected that such processessing is
/// immediate.
/// @param from message block from client
/// @param to message block to client
void DirectProcess (Detail::MessageBuffer &from, Detail::MessageBuffer &to);
public:
/// Process the messages queued in the read buffer. We enter the
/// PROCESSING state, and each message line causes various resolver
/// methods to be called. Once processed, the server may need to
/// wait for all the requests to be ready, or it may be able to
/// immediately write responses back.
void ProcessRequests ();
public:
/// Accumulate an error response.
/// @param error the error message to encode
/// @param elen length of error, if known
void ErrorResponse (char const *error, size_t elen = ~size_t (0));
void ErrorResponse (std::string const &error)
{
ErrorResponse (error.data (), error.size ());
}
/// Accumulate an OK response
void OKResponse ();
/// Accumulate a boolean response
void BoolResponse (bool);
/// Accumulate a pathname response
/// @param path (may be nullptr, or empty)
/// @param rlen length, if known
void PathnameResponse (char const *path, size_t plen = ~size_t (0));
void PathnameResponse (std::string const &path)
{
PathnameResponse (path.data (), path.size ());
}
public:
/// Accumulate a (successful) connection response
/// @param agent the server-side agent
/// @param alen agent length, if known
void ConnectResponse (char const *agent, size_t alen = ~size_t (0));
void ConnectResponse (std::string const &agent)
{
ConnectResponse (agent.data (), agent.size ());
}
public:
/// Write message block to client. Semantics as for
/// MessageBuffer::Write.
/// @result errno or completion (0).
int Write ()
{
return write.Write (fd.to);
}
/// Initialize for writing a message block. All responses to the
/// incomping message block must be complete Enters WRITING state.
void PrepareToWrite ()
{
write.PrepareToWrite ();
direction = WRITING;
}
public:
/// Read message block from client. Semantics as for
/// MessageBuffer::Read.
/// @result errno, eof (-1) or completion (0)
int Read ()
{
return read.Read (fd.from);
}
/// Initialize for reading a message block. Enters READING state.
void PrepareToRead ()
{
read.PrepareToRead ();
direction = READING;
}
};
// Helper network stuff
#if CODY_NETWORKING
// Socket with specific address
int OpenSocket (char const **, sockaddr const *sock, socklen_t len);
int ListenSocket (char const **, sockaddr const *sock, socklen_t len,
unsigned backlog);
// Local domain socket (eg AF_UNIX)
int OpenLocal (char const **, char const *name);
int ListenLocal (char const **, char const *name, unsigned backlog = 0);
// ipv6 socket
int OpenInet6 (char const **e, char const *name, int port);
int ListenInet6 (char const **, char const *name, int port,
unsigned backlog = 0);
#endif
// FIXME: Mapping file utilities?
}
#endif // CODY_HH