Le 06/07/2020 à 14:12, David Leangen a écrit : > Thanks Benoit. > > Now, since I already have your attention on this topic, please allow me to > really push so I can reach some kind of resolution. The resolution will allow > me to figure out how to move forward with several things. Since I have been a > bit stuck the past few days (and growing frustrated a little 😅) I hope you > can continue to help me resolve this. I gonna try my best, given my time constraints :-) > Let me keep the focus on the SMTP module, because I think we’ll likely be > able to extrapolate much of the approach to the other modules as well. > > I think this is what we seem to agree on: > > * Separation of API and implementation is generally a good thing (especially > if we want clean components) > * The current API is a bit messy and could use some cleaning > * However, the value of making any changes is questionable at this time > > > Here are also a few things I have discovered on this journey: > > * Actually implementing RFC5321 as a Java API would be VERY challenging > - The spec is fairly complex > - The spec is very “messy” and not very well or precisely written IMO > * As you pointed out, there are some important elements in the James SMTP > module, such as commands and hooks > - These ought to be somehow highlighted and improved in the API +1 > * You have mentioned more than once that it uses a hexagonal architecture > - I think this is important, but I still don’t know what to do about it > > > So I guess my question is this: what should I do in the immediate term? As > you and others have pointed out (and me also), the documents should show what > James *is*, not what James *aspires to be*. In my opinions we should document "How to write hooks with the protocols/smtp library", "How to plug such hooks into a running James server"
Then "How to write commands for the protocols/smtp library" (and how to plug them in James) Using protocols-smtp without the server/protocols/protocols-netty super layer would be so far a non-goal to me, and I would likely not be able to help you do this. > So what is the SMTP module, and how should I describe it? I would state `james-project/protocols/protocols-smtp` is a transport agnostic implementation of (some of) the SMTP specifications. It is customizable (hooks) and extensible (additional commands). `james-project/server/protocols/protocols-smtp` adapts `james-project/protocols/protocols-smtp` in the James context, providing hooks interacting with James server components. It also provides a TCP transport layer, effectively providing a SMTP server. Does it answers your question? > In the part of the docs entitled “James model”, if I were to write in all > honesty I don’t feel that there is a clear model, or at least it is totally > not clear (to me) from the API. James is an implementation of RFC5321, and > basically makes no attempt to have a clear java API. Rather, the API is via > JMX. (I will have to investigate further to see what the JMX view of the > system is.) Ouch. Please don't. It's old, not clean, mostly unmaintained, and likely to be removed in the (not that far) future - for security reasons because JMX. Don't hesitate if you want details on this statement (maybe a separate thread?) To 'operate' James we should prefer webadmin. That will mean providing CLI tool on top of it for the less technical of our users. What do you try to achieve? (I don't see the link making you go from SMTP to JMX to be honnest) > I could mention that there is a “plan” to create cleaner java apis. > > That’s about all I can think of right now. Would this approach be acceptable? There's always a plan in my opinion to consider API enhancement proposals :-) > >>>> Note that "standard SMTP commands" are bundled into a single >>>> ProtocolHandler, not relying on it means you defines your very own SMTP >>>> commands. >>> Ok, these are the types of things that I am very interested in >>> understanding better. Are there any docs anywhere to help me out?Not really >> Not really. >> >> http://james.apache.org/server/dev-provided-smtp-hooks.html defines hook >> you can rely in for the default implementation. >> >> https://github.com/apache/james-project/blob/master/src/site/xdoc/server/dev-extend-smtp-hook.xml >> might be helpful too. >> >> Which is not much for "hooks" already. Given the part of the quote you >> chose, that might not be what you are looking for... >> >> Regarding writing your own commands, there is even less. >> >> http://james.apache.org/protocols/index.html is too generic >> >> http://james.apache.org/protocols/smtp.html is blank > Would it be useful for me to pursue this in an attempt to document the SMTP > module? I could try, but again I’ll most likely need help. > > Or should I write something like what I mention above and just be done with > it for now? You proved us writing documentation (and software) needs to be performed with a usage in mind. I would upvote (and support given my available time) documenting the extension mechanisms of the existing protocols-smtp project. (so hooks and commands) Rationals: that's the most straightforward use case for protocols-smtp, and the documentation work should not be too hard to perform. (I forgot to mention https://github.com/chibenwa/james-blacklist/blob/master/blacklist-smtp/src/main/java/com/linagora/james/blacklist/smtp/NotInBlackListHook.java is an example of how to define a Rcpt hook, and the rest of the project shows how to load it in a guice james server) Cheers, Benoit --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
