Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add WIP API module #1803

Draft
wants to merge 10 commits into
base: master
Choose a base branch
from
Draft

Add WIP API module #1803

wants to merge 10 commits into from

Conversation

strugee
Copy link

@strugee strugee commented Aug 5, 2021

This adds a work-in-progress *api user that provides programmatic access to many aspects of ZNC. I intend to add the ability to set many of these values as well as query and set network information before I consider this fully useful.

I don't know if anyone is interested in pulling this in upstream, so I figured I would open this PR to see. If not I will likely maintain it as an external module. I would also be interested in code style feedback, as it's been ~a decade since I seriously wrote C++ and I'm rusty to say the least :P

Ref #1770

@strugee
Copy link
Author

strugee commented Aug 5, 2021

Also, a little bit about the API design: it's supposed to feel a little bit like SMTP. I like the all-caps style of SMTP so that's what things are written in, but input is case-insensitive (so far; obviously user-specified strings like network names won't be). There's a notion of a top-level command, which is generally just, the thing you're doing. Currently there's just QUERY and PING, but I expect to add SET and a few others in the future, e.g. cloning networks will probably be available via a toplevel command CLONE (though I haven't thought about it that much).

QUERY has a notion of scopes, which is basically what you'd expect - it's the general area in ZNC where you want to query values. In the code that's currently written scopes are static but I'm planning for each network to define a dynamic scope, so you'll be able to do e.g. QUERY libera NICK to get the nickname the user uses specifically on Libera.chat, assuming they have a network configured named libera.

Errors are borrowed from Unix because people tend to grok those already. The first space-delimited word is the general error code and then an explanation is provided in the rest of the string. The intention is that clients will be able to look at the general error code and do something useful even if they don't recognize the specific error string. The intention is to keep these strings and error codes stable over time.

Whether or not this gets pulled into ZNC core or I end up maintaining it out-of-tree, I intend to document the whole API on the ZNC wiki. Feedback on the API design or style would be super helpful.

@lgtm-com
Copy link

lgtm-com bot commented Aug 5, 2021

This pull request introduces 1 alert when merging f20462c into 9cd3605 - view on LGTM.com

new alerts:

  • 1 for Missing return statement

@strugee
Copy link
Author

strugee commented Aug 5, 2021

LGTM alert is spurious.

@strugee
Copy link
Author

strugee commented Aug 5, 2021

Fixed the LGTM alert; thanks @DarthGandalf on IRC.

I've done some stuff that returns lists now. Open question: should the LIST type just become TUPLELIST 1? I feel like yes since there seems to be no reason for these to be separate. (It doesn't really matter for programmatic consumers obviously, but one goal of mine is to make this API essentially intuitively understandable/explorable by manually sending commands to the *api user and this would make the API more consistent.)

And make scalar values prefixed with VALUE, which is necessary to
disambiguate a true NULL response and the string "NULL" which could e.g.
be set as someone's nickname.
At the same time, make COMMANDS and QUERYSCOPES dynamically load their
results from the mapping tables. (The exception to this is network
scopes, for now.)
@strugee
Copy link
Author

strugee commented Oct 19, 2021

This needs a deprecation plan - maybe have a notion of a "warning" that's encountered during processing, but isn't fatal?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

None yet

1 participant