2 * InspIRCd -- Internet Relay Chat Daemon
4 * Copyright (C) 2018-2020 Sadie Powell <sadie@witchery.services>
5 * Copyright (C) 2018 Attila Molnar <attilamolnar@hush.com>
7 * This file is part of InspIRCd. InspIRCd is free software: you can
8 * redistribute it and/or modify it under the terms of the GNU General Public
9 * License as published by the Free Software Foundation, version 2.
11 * This program is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
13 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
16 * You should have received a copy of the GNU General Public License
17 * along with this program. If not, see <http://www.gnu.org/licenses/>.
25 namespace ClientProtocol
34 /** Contains a message parsed from wire format.
35 * Used by Serializer::Parse().
37 struct ClientProtocol::ParseOutput
39 /** Command name, must not be empty.
43 /** Parameter list, may be empty.
45 ClientProtocol::ParamList params;
47 /** Message tags, may be empty.
49 ClientProtocol::TagMap tags;
52 /** A selection of zero or more tags in a TagMap.
54 class ClientProtocol::TagSelection
56 std::bitset<64> selection;
59 /** Check if a tag is selected.
60 * @param tags TagMap the tag is in. The TagMap must contain the same tags as it had when the tag
61 * was selected with Select(), otherwise the result is not meaningful.
62 * @param it Iterator to the tag to check.
63 * @return True if the tag is selected, false otherwise.
65 bool IsSelected(const TagMap& tags, TagMap::const_iterator it) const
67 const size_t index = std::distance(tags.begin(), it);
68 return ((index < selection.size()) && (selection[index]));
72 * @param tags TagMap the tag is in. This parameter must be the same every time the method is called.
73 * The TagMap must not be altered otherwise the results of IsSelected() is not meaningful.
74 * @param it Iterator to the tag to mark as selected.
76 void Select(const TagMap& tags, TagMap::const_iterator it)
78 const size_t index = std::distance(tags.begin(), it);
79 if (index < selection.size())
80 selection[index] = true;
83 /** Check if a TagSelection is equivalent to this object.
84 * @param other Other TagSelection object to compare this with.
85 * @return True if the objects are equivalent, false if they aren't.
87 bool operator==(const TagSelection& other) const
89 return (this->selection == other.selection);
93 class ClientProtocol::MessageSource
96 const std::string* sourcestr;
99 /** Constructor, sets the source to be the full host of a user or sets it to be nothing.
100 * The actual source string when serializing will be obtained from User::GetFullHost() if the user is non-NULL.
101 * @param Sourceuser User to set as source of the message. If NULL, the message won't have a source when serialized.
102 * Optional, defaults to NULL.
104 MessageSource(User* Sourceuser = NULL)
106 SetSourceUser(Sourceuser);
109 /** Constructor, sets the source to the supplied string and optionally sets the source user.
110 * @param Sourcestr String to use as message source for serialization purposes. Must remain valid
111 * as long as this object is alive.
112 * @param Sourceuser User to set as source. Optional, defaults to NULL. It will not be used for serialization but
113 * if provided it may be used internally, for example to create message tags.
114 * Useful when the source string is synthesized but it is still related to a User.
116 MessageSource(const std::string& Sourcestr, User* Sourceuser = NULL)
118 SetSource(Sourcestr, Sourceuser);
121 /** Get the source of this message as a string.
122 * @return Pointer to the message source string or NULL if there is no source.
124 const std::string* GetSource() const
126 // Return string if there's one explicitly set
130 return &sourceuser->GetFullHost();
134 /** Get the source User.
135 * This shouldn't be used for serialization, use GetSource() for that.
136 * @return User pointer if the message has a source user, NULL otherwise.
138 User* GetSourceUser() const { return sourceuser; }
140 /** Set the source of this message to a User.
141 * See the one parameter constructor for a more detailed description.
142 * @param Sourceuser User to set as source.
144 void SetSourceUser(User* Sourceuser)
146 sourceuser = Sourceuser;
150 /** Set the source string and optionally source user.
151 * See the two parameter constructor for a more detailed description.
152 * @param Sourcestr String source, to be used for serialization purposes. Must remain valid as long
153 * as this object is alive.
154 * @param Sourceuser Source user to set, optional.
156 void SetSource(const std::string& Sourcestr, User* Sourceuser = NULL)
158 sourcestr = &Sourcestr;
159 sourceuser = Sourceuser;
162 /** Copy the source from a MessageSource object.
163 * @param other MessageSource object to copy from.
165 void SetSource(const MessageSource& other)
167 sourcestr = other.sourcestr;
168 sourceuser = other.sourceuser;
172 /** Outgoing client protocol message.
173 * Represents a high level client protocol message which is turned into raw or wire format
174 * by a Serializer. Messages can be serialized into different format by different serializers.
176 * Messages are created on demand and are disposed of after they have been sent.
178 * All messages have a command name, a list of parameters and a map of tags, the last two can be empty.
179 * They also always have a source, see class MessageSource.
181 class ClientProtocol::Message : public ClientProtocol::MessageSource
184 /** Contains information required to identify a specific version of a serialized message.
186 struct SerializedInfo
188 const Serializer* serializer;
192 * @param Ser Serializer used to serialize the message.
193 * @param Tagwl Tag whitelist used to serialize the message.
195 SerializedInfo(const Serializer* Ser, const TagSelection& Tagwl)
201 /** Check if a SerializedInfo object is equivalent to this object.
202 * @param other Other SerializedInfo object.
203 * @return True if other is equivalent to this object, false otherwise.
205 bool operator==(const SerializedInfo& other) const
207 return ((serializer == other.serializer) && (tagwl == other.tagwl));
213 const std::string* ptr;
214 insp::aligned_storage<std::string> str;
217 void InitFrom(const Param& other)
221 new(str) std::string(*other.str);
227 operator const std::string&() const { return (owned ? *str : *ptr); }
235 Param(const std::string& s)
241 Param(int, const char* s)
244 new(str) std::string(s);
247 Param(int, const std::string& s)
250 new(str) std::string(s);
253 Param(const Param& other)
265 Param& operator=(const Param& other)
277 bool IsOwned() const { return owned; }
280 typedef std::vector<Param> ParamList;
283 typedef std::vector<std::pair<SerializedInfo, SerializedMessage> > SerializedList;
289 mutable SerializedList serlist;
293 /** Set command string.
294 * @param cmd Command string to set.
296 void SetCommand(const char* cmd)
305 * @param cmd Command name, e.g. "JOIN", "NICK". May be NULL. If NULL, the command must be set
306 * with SetCommand() before the message is serialized.
307 * @param Sourceuser See the one parameter constructor of MessageSource for description.
309 Message(const char* cmd, User* Sourceuser = NULL)
310 : ClientProtocol::MessageSource(Sourceuser)
311 , command(cmd ? cmd : std::string())
312 , msginit_done(false)
320 * @param cmd Command name, e.g. "JOIN", "NICK". May be NULL. If NULL, the command must be set
321 * with SetCommand() before the message is serialized.
322 * @param Sourcestr See the two parameter constructor of MessageSource for description.
323 * Must remain valid as long as this object is alive.
324 * @param Sourceuser See the two parameter constructor of MessageSource for description.
326 Message(const char* cmd, const std::string& Sourcestr, User* Sourceuser = NULL)
327 : ClientProtocol::MessageSource(Sourcestr, Sourceuser)
328 , command(cmd ? cmd : std::string())
329 , msginit_done(false)
336 /** Get the parameters of this message.
337 * @return List of parameters.
339 const ParamList& GetParams() const { return params; }
341 /** Get a map of tags attached to this message.
342 * The map contains the tag providers that attached the tag to the message.
343 * @return Map of tags.
345 const TagMap& GetTags() const { return tags; }
347 /** Get the command string.
348 * @return Command string, e.g. "NICK", "001".
350 const char* GetCommand() const { return command.c_str(); }
352 /** Add a parameter to the parameter list.
353 * @param str String to add, will be copied.
355 void PushParam(const char* str) { params.push_back(Param(0, str)); }
357 /** Add a parameter to the parameter list.
358 * @param str String to add, will be copied.
360 void PushParam(const std::string& str) { params.push_back(Param(0, str)); }
362 /** Add a parameter to the parameter list.
363 * @param str String to add.
364 * The string will NOT be copied, it must remain alive until ClearParams() is called or until the object is destroyed.
366 void PushParamRef(const std::string& str) { params.push_back(str); }
368 /** Add a placeholder parameter to the parameter list.
369 * Placeholder parameters must be filled in later with actual parameters using ReplaceParam() or ReplaceParamRef().
371 void PushParamPlaceholder() { params.push_back(Param()); }
373 /** Replace a parameter or a placeholder that is already in the parameter list.
374 * @param index Index of the parameter to replace. Must be less than GetParams().size().
375 * @param str String to replace the parameter or placeholder with, will be copied.
377 void ReplaceParam(unsigned int index, const char* str) { params[index] = Param(0, str); }
379 /** Replace a parameter or a placeholder that is already in the parameter list.
380 * @param index Index of the parameter to replace. Must be less than GetParams().size().
381 * @param str String to replace the parameter or placeholder with, will be copied.
383 void ReplaceParam(unsigned int index, const std::string& str) { params[index] = Param(0, str); }
385 /** Replace a parameter or a placeholder that is already in the parameter list.
386 * @param index Index of the parameter to replace. Must be less than GetParams().size().
387 * @param str String to replace the parameter or placeholder with.
388 * The string will NOT be copied, it must remain alive until ClearParams() is called or until the object is destroyed.
390 void ReplaceParamRef(unsigned int index, const std::string& str) { params[index] = Param(str); }
393 * @param tagname Raw name of the tag to use in the protocol.
394 * @param tagprov Provider of the tag.
395 * @param val Tag value. If empty no value will be sent with the tag.
396 * @param tagdata Tag provider specific data, will be passed to MessageTagProvider::ShouldSendTag(). Optional, defaults to NULL.
398 void AddTag(const std::string& tagname, MessageTagProvider* tagprov, const std::string& val, void* tagdata = NULL)
400 tags.insert(std::make_pair(tagname, MessageTagData(tagprov, val, tagdata)));
403 /** Add all tags in a TagMap to the tags in this message. Existing tags will not be overwritten.
404 * @param newtags New tags to add.
406 void AddTags(const ClientProtocol::TagMap& newtags)
408 tags.insert(newtags.begin(), newtags.end());
411 /** Get the message in a serialized form.
412 * @param serializeinfo Information about which exact serialized form of the message is the caller asking for
413 * (which serializer to use and which tags to include).
414 * @return Serialized message according to serializeinfo. The returned reference remains valid until the
415 * next call to this method.
417 const SerializedMessage& GetSerialized(const SerializedInfo& serializeinfo) const;
419 /** Clear the parameter list and tags.
423 msginit_done = false;
429 /** Remove all serialized messages.
430 * If a parameter is changed after the message has been sent at least once, this method must be called before
431 * serializing the message again to ensure the cache won't contain stale data.
433 void InvalidateCache()
441 for (ParamList::iterator i = params.begin(); i != params.end(); ++i, j++)
445 ReplaceParam(j, curr);
449 void SetSideEffect(bool Sideeffect) { sideeffect = Sideeffect; }
450 bool IsSideEffect() const { return sideeffect; }
452 friend class Serializer;
455 /** Client protocol event class.
456 * All messages sent to a user must be part of an event. A single event may result in more than one protocol message
457 * being sent, for example a join event may result in a JOIN and a MODE protocol message sent to members of the channel
458 * if the joining user has some prefix modes set.
460 * Event hooks attached to a specific event can alter the messages sent for that event.
462 class ClientProtocol::Event
464 EventProvider* event;
466 const MessageList* initialmsglist;
471 * @param protoeventprov Protocol event provider the event is an instance of.
473 Event(EventProvider& protoeventprov)
474 : event(&protoeventprov)
476 , initialmsglist(NULL)
477 , eventinit_done(false)
482 * @param protoeventprov Protocol event provider the event is an instance of.
483 * @param msg Message to include in this event by default.
485 Event(EventProvider& protoeventprov, ClientProtocol::Message& msg)
486 : event(&protoeventprov)
488 , initialmsglist(NULL)
489 , eventinit_done(false)
493 /** Set a single message as the initial message in the event.
494 * Modules may alter this later.
496 void SetMessage(Message* msg)
499 initialmsglist = NULL;
502 /** Set a list of messages as the initial messages in the event.
503 * Modules may alter this later.
505 void SetMessageList(const MessageList& msglist)
508 initialmsglist = &msglist;
511 /** Get a list of messages to send to a user.
512 * The exact messages sent to a user are determined by the initial message(s) set and hooks.
513 * @param user User to get the messages for.
514 * @param messagelist List to fill in with messages to send to the user for the event
516 void GetMessagesForUser(LocalUser* user, MessageList& messagelist);
519 class ClientProtocol::MessageTagEvent
520 : public Events::ModuleEventProvider
523 MessageTagEvent(Module* mod)
524 : ModuleEventProvider(mod, "event/messagetag")
529 /** Base class for message tag providers.
530 * All message tags belong to a message tag provider. Message tag providers can populate messages
531 * with tags before the message is sent and they have the job of determining whether a user should
532 * get a message tag or be allowed to send one.
534 class ClientProtocol::MessageTagProvider : public Events::ModuleEventListener
538 * @param mod Module owning the provider.
540 MessageTagProvider(Module* mod)
541 : Events::ModuleEventListener(mod, "event/messagetag")
545 /** Called when a message is ready to be sent to give the tag provider a chance to add tags to the message.
546 * To add tags call Message::AddTag(). If the provided tag or tags have been added already elsewhere or if the
547 * provider doesn't want its tag(s) to be on the message, the implementation doesn't have to do anything special.
548 * The default implementation does nothing.
549 * @param msg Message to be populated with tags.
551 virtual void OnPopulateTags(ClientProtocol::Message& msg)
555 /** Called for each tag that the server receives from a client in a message.
556 * @param user User that sent the tag.
557 * @param tagname Name of the tag.
558 * @param tagvalue Value of the tag, empty string if the tag has no value. May be modified.
559 * @return MOD_RES_ALLOW to accept the tag with the value in 'value', MOD_RES_DENY to reject the tag and act as if it wasn't sent,
560 * MOD_RES_PASSTHRU to make no decision. If no hooks accept a tag, the tag is rejected.
561 * The default implementation returns MOD_RES_PASSTHRU.
563 virtual ModResult OnProcessTag(User* user, const std::string& tagname, std::string& tagvalue)
565 return MOD_RES_PASSTHRU;
568 /** Called whenever a user is about to receive a message that has a tag attached which is provided by this provider
569 * to determine whether or not the user should get the tag.
570 * @param user User in question.
571 * @param tagdata Tag in question.
572 * @return True if the tag should be sent to the user, false otherwise.
574 virtual bool ShouldSendTag(LocalUser* user, const MessageTagData& tagdata) = 0;
577 /** Base class for client protocol event hooks.
578 * A protocol event hook is attached to a single event type. It has the ability to alter or block messages
579 * sent to users which belong to the event the hook is attached to.
581 class ClientProtocol::EventHook : public Events::ModuleEventListener
584 static std::string GetEventName(const std::string& name)
586 return "event/protoevent_" + name;
590 * @param mod Owner of the hook.
591 * @param name Name of the event to hook.
592 * @param priority Priority of the hook. Determines the order in which hooks for the same event get called.
595 EventHook(Module* mod, const std::string& name, unsigned int priority = Events::ModuleEventListener::DefaultPriority)
596 : Events::ModuleEventListener(mod, GetEventName(name), priority)
600 /** Called exactly once before an event is sent to any user.
601 * The default implementation doesn't do anything.
602 * @param ev Event being sent to one or more users.
604 virtual void OnEventInit(const ClientProtocol::Event& ev)
608 /** Called for each user that may receive the event.
609 * The hook may alter the messages sent to the user and decide whether further hooks should be executed.
610 * @param user User the message list is being prepared to be sent to.
611 * @param ev Event associated with the messages.
612 * @param messagelist List of messages to send to the user. The hook can alter this in any way it sees fit, for example it can replace messages,
613 * add new messages, etc. The list must not be empty when the method returns.
614 * @return MOD_RES_PASSTHRU to run hooks after the called hook or if no hooks are after the called hook, send the messages in messagelist to the user.
615 * MOD_RES_DENY to not send any messages to the user and to not run other hooks,
616 * MOD_RES_ALLOW to send the messages in messagelist to the user and to not run other hooks.
618 virtual ModResult OnPreEventSend(LocalUser* user, const ClientProtocol::Event& ev, ClientProtocol::MessageList& messagelist) = 0;
621 /** Event provider for client protocol events.
622 * Protocol event hooks can be attached to the instances of these providers. The core has event
623 * providers for most common IRC events defined in RFC1459.
625 class ClientProtocol::EventProvider : public Events::ModuleEventProvider
629 * @param Mod Module that owns the event provider.
630 * @param eventname Name of the event this provider is for, e.g. "JOIN", "PART", "NUMERIC".
631 * Should match command name if applicable.
633 EventProvider(Module* Mod, const std::string& eventname)
634 : Events::ModuleEventProvider(Mod, ClientProtocol::EventHook::GetEventName(eventname))
639 /** Commonly used client protocol events.
640 * Available via InspIRCd::GetRFCEvents().
642 struct ClientProtocol::RFCEvents
644 EventProvider numeric;
652 EventProvider privmsg;
653 EventProvider invite;
659 : numeric(NULL, "NUMERIC")
666 , topic(NULL, "TOPIC")
667 , privmsg(NULL, "PRIVMSG")
668 , invite(NULL, "INVITE")
671 , error(NULL, "ERROR")
676 /** Base class for client protocol serializers.
677 * A serializer has to implement serialization and parsing of protocol messages to/from wire format.
679 class CoreExport ClientProtocol::Serializer : public DataProvider
682 ClientProtocol::MessageTagEvent evprov;
684 /** Make a white list containing which tags a user should get.
685 * @param user User in question.
686 * @param tagmap Tag map that contains all possible tags.
687 * @return Whitelist of tags to send to the user.
689 TagSelection MakeTagWhitelist(LocalUser* user, const TagMap& tagmap) const;
693 * @param mod Module owning the serializer.
694 * @param Name Name of the serializer, e.g. "rfc".
696 Serializer(Module* mod, const char* Name);
698 /** Handle a tag in a message being parsed. Call this method for each parsed tag.
699 * @param user User sending the tag.
700 * @param tagname Name of the tag.
701 * @param tagvalue Tag value, may be empty.
702 * @param tags TagMap to place the tag into, if it gets accepted.
703 * @return True if no error occurred, false if the tag name is invalid or if this tag already exists.
705 bool HandleTag(LocalUser* user, const std::string& tagname, std::string& tagvalue, TagMap& tags) const;
707 /** Serialize a message for a user.
708 * @param user User to serialize the message for.
709 * @param msg Message to serialize.
710 * @return Raw serialized message, only containing the appropriate tags for the user.
711 * The reference is guaranteed to be valid as long as the Message object is alive and until the same
712 * Message is serialized for another user.
714 const SerializedMessage& SerializeForUser(LocalUser* user, Message& msg);
716 /** Serialize a high level protocol message into wire format.
717 * @param msg High level message to serialize. Contains all necessary information about the message, including all possible tags.
718 * @param tagwl Message tags to include in the serialized message. Tags attached to the message but not included in the whitelist must not
719 * appear in the output. This is because each user may get a different set of tags for the same message.
720 * @return Protocol message in wire format. Must contain message delimiter as well, if any (e.g. CRLF for RFC1459).
722 virtual std::string Serialize(const Message& msg, const TagSelection& tagwl) const = 0;
724 /** Parse a protocol message from wire format.
725 * @param user Source of the message.
726 * @param line Raw protocol message.
727 * @param parseoutput Output of the parser.
728 * @return True if the message was parsed successfully into parseoutput and should be processed, false to drop the message.
730 virtual bool Parse(LocalUser* user, const std::string& line, ParseOutput& parseoutput) = 0;
733 inline ClientProtocol::MessageTagData::MessageTagData(MessageTagProvider* prov, const std::string& val, void* data)