KNOCK command.

[HelixSpiral]

Updated 3March2014

There's been a lot of discussion over IRC about the current implementation and how it appears to differ from implementation to implementation. Also some people don't like knock having it's own numerics.

In light of this, I think the best course is to go with a KNOCK cap, if it's enabled then we follow our implementation, if it's not enabled then we don't care. It'll fall-back to whatever the current server has decided to use for their implementation.

What we've got so far: With no message: :knocking-user!ident@host KNOCK #chan With message: :knocking-user!ident@host KNOCK #chan :user-message

We'll still need to form some sort of error message to give out if the channel is blocking knocks (+K on some servers) and similar. But this seems to be a good basis.

[attilamolnar]

A new cap was proposed for knock notification which will contain the description of a standarized knock notification message deprecating the current "send notice to channel" and "send numeric to channel" approaches.

[k4bek4be]

Let's try... Changes: changed replies to inspircd/ratbox numerics, added isupport This spec defines a new knock capability and a KNOCK command and message, attemtping to standarize functionality already used on IRC. The purpose of this functionality is to allow clients to ask for access to invite-only (+i) channels. Servers MAY allow using this for circumventing other channel restrictions too. A KNOCK ISUPPORT tag SHOULD be provided by the server to match existing implementations.

The format of KNOCK command is: KNOCK <channel> :<message>

The format of KNOCK notification is: :<knocking user> KNOCK <channel> :<message>

The message MAY be allowed to be omitted. Above notification MUST be sent to all channel operators with access of a predefined access level (suggested +o or higher), and to the user issuing the KNOCK command. Servers MUST allow using of the KNOCK command by users who have not negotiated the knock capability. The server MAY use legacy replies in this case. Servers MUST also notify channel operators who have not negotiated the knock capability. In this case, the KNOCK notification will not be used. Instead, servers SHALL send notifications in the style defined by legacy implementations (for example as a NOTICE message or numerics). Channel operators should decide whether to /invite the KNOCKing user. Servers MAY restrict the usage of the KNOCK command. It is suggested than a +K channel mode char is used to disable all KNOCKs to a channel. The KNOCK request SHOULD be also rejected for channels which don't allow using INVITE, or when nothing restricts the KNOCKing user to join this channel. Servers MAY also disallow KNOCKing multiple times to a single channel.

Numeric replies are defined as following (final arguments may be altered):

Numeric	Name	Format
480	ERR_CANNOTKNOCK	:<server> ERR_CANNOTKNOCK <nickname> <channel> :<reason>
711	RPL_KNOCKDLVR	:<server> RPL_KNOCKDLVR <nickname> <channel> :Knocked on channel
713	ERR_CHANOPEN	:<server> ERR_CHANOPEN <nickname> <channel> :<reason>
714	ERR_KNOCKONCHAN	:<server> ERR_KNOCKONCHAN <nickname> <channel> :You're already on that channel

Legacy 710 RPL_KNOCK (if used) is replaced by the KNOCK notification for clients with knock cap enabled.

Examples of rejected KNOCKs:

KNOCK is not allowed on this channel: :<server> ERR_CANNOTKNOCK <nickname> <channel> :This channel does not accept knocking.

Channel is free to join: :<server> ERR_CHANOPEN <nickname> <channel> :Channel is not invite-only

Multiple KNOCKs: :<server> ERR_CANNOTKNOCK <nickname> <channel> :Already knocked

Usage examples:

Client with "knock" cap:	KNOCK #test :Let me in
Server to client:	:irc.example.com RPL_KNOCKDLVR some #test :Knocked on channel
Server to chanops with "knock" cap:	:[email protected] KNOCK #test :Let me in
Server to chanops without this cap:	:irc.example.com NOTICE @#test :[KNOCK] [email protected] is knocking: Let me in

Client without "knock" cap:	KNOCK #test :Let me in
Server to client:	:irc.example.com NOTICE some :Knocked on #test

[SadieCat]

There's already knock numerics. Can we use those instead of standard replies please?

https://github.com/inspircd/inspircd/blob/insp3/src/modules/m_knock.cpp#L30-L40

[syzop]

A server sends numerics in response to a client issued command (to that client). Sending numerics "out of nowhere" is not standard IRC protocol practice. For events we have commands in IRC. So making KNOCK work the same as INVITE with invite-notify (:xyz KNOCK #target :text) with a new knock-notify makes sense to me.

[syzop]

I see a few people just downvoting or saying negative things without trying to actually counter my argument (not just here but i saw some activity on my dev channel history of last night). A variant of the "IRC would still be stuck with ascii" argument popped up even. I don't think that's very constructive. Similarly, I thought my argument was "so clear" that it did not need a longer explanation. Apparently that was an incorrect assumption and in that light I can see how my short answer can come across as arrogant to some.

So, allow me to expand my comment into a longer version below:

Numerics vs commands (short version)

In my experience, IRC numerics are sent back to the requestor in direct response to commands. I also think that is why they are called numeric replies in RFC1459 section 2.4 (plus another 40 times in that document). It's a server reply to a client request. The only exceptions to this rule, that I can think of right now, is when you are connecting/disconnecting and in WATCH/MONITOR. Anyway, whether you can find one or a few more exceptions than I mention here, whether this rule is 100% true, 98% or 95%, I think we can all agree that there is a clear tendency here, right?

Channel events

Let's focus on channel events. This is channel activity that takes place after you have fully joined. These can be user-triggered or server-triggered (eg netsplit). We have the following standard IRC channel events: JOIN PART KICK MODE TOPIC PRIVMSG NOTICE (QUIT) (NICK) In IRCv3 we have the following new events: TAGMSG, INVITE, (AWAY), (CHGHOST)

(The ones in brackets are send to common channels. These can also be recognized by lacking a channel argument.)

There are no channel events sent as numerics. Well, other than numeric 710 in this thread, which is what this debate is about.

Benefit of numerics

You can see how the four IRCv3 events are all conditionally sent commands, they are only sent after some CAP negotiation. This because it is uncommon to send unknown/new IRC protocol commands if the client does not support it. On the other hand, numerics give you more freedom here: a server coder can invent a new numeric and start sending it from day 1. Clients may then later add support (or not).

Benefit of commands

Commands are used to relay events, and there are benefits to the numerics/commands difference. Numerics always originate from a server (server source). With commands they can originate from users. It is immediately clear from who a command/event is originating. It gives the nick!user@host automatically, which usually gets converted to a client struct or similar and thus similar variables in client scripts such as $nick and $host. It also gives tags like @account and @unrealircd.org/userip and @inspircd.org/bot, which again on the client-side and script-side for example in mIRC translate to $msgtags(account). That being said, after re-reading the account-tag spec, I read servers are supposed to send the account-tag for numerics as well. This sounds more like a hack to me, but okay. In any case, that often requires additional (explicit) server code, in contrast to source based addition of tags which often happens automatically. As an example, this may be the reason why InspIRCd is not sending account-tag in the 710 numeric, it is so easy to forget.

In any case, the nice thing about originating nick!user@host and adding tags is that all this information is provided via an universal way (API, usually) within clients and servers and to scripts. No need to think like oh this must be parameter 3 or 5 and scripts don't need to use $1 to access this universal stuff, you can just use $nick etc. Furthermore, it is extendable with more tags, without having to change the command or numeric, without breaking clients.

Why a numeric was used in this case...

So, while I don't agree with it, I can see why someone started using a numeric for KNOCK events in an IRCd years ago. We did not have IRCv3 yet, and as explained earlier, you cannot really start using a new command but you can use a new numeric before clients support it. So presumably they started using the numeric so they could have solution at that very moment, since day 1.

But why not for INVITE...?

This one I do not know. I cannot explain why an IRCd used a numeric for KNOCK but not for INVITE (or did they?). At least in my head, INVITE and KNOCK and also invite-notify and knock-notify, are closely related. If I put my own hat off and imagine all I was saying was nonsense and numerics are totally fine to send to channels, imagine that this is the position, then I cannot explain:

1. Why there is an invite-notify spec, while you could have used a numeric.
2. Why it was OK to move notices (in UnrealIRCd) to a new invite-notify spec, but why moving numerics (in ratbox) or notices (again, in UnrealIRCd) to a knock-notify spec, would not qualify.

Conclusion

Really, the only reason for using numerics for KNOCK channel events is that it is already implemented by a number of clients/servers. Am I saying that single argument is not a good one? No, not at all, it can be a good argument, and we can talk about that, certainly, and weigh that argument with the other arguments in favor and against. I am just saying that the argument that sending numerics is completely normal (nothing out of the ordinary) for channel events is not true. I think you should be honest about that. Just recognize the strong points of your arguments and the weak points.