You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@trafficserver.apache.org by Zeyuan Yu <ze...@gmail.com> on 2019/05/01 19:07:01 UTC
API Proposal: SSL client context retrieval
vector<string> TSSslClientContextsGet();
TSSslContext TSSslClientContextFind(const string name);
ATS has APIs for server context retrieval (TSSslContextFindByName(),
TSSslContextFindByAddr()). It would be useful to expose client context via
APIs too.
I would like to propose new APIs for this purpose. Given client context are
stored in unordered_map, TSSslClientContextsGet() will return all keys
(essentially the path to CA/cert files) in a vector;
TSSslClientContextFid() will return the context corresponding to the input
string.
[image: work-eat-sleep--400090.jpg]
*Zeyuan Yu*
Software Development Engineer, Verizon Media Group
work: 217.369.5086
personal: 217.898.1085
Re: API Proposal: SSL client context retrieval
Posted by Walt Karas <wk...@verizonmedia.com.INVALID>.
I think the main barrier to good documentation is the amount of reverse
engineer it would require at this point.
I've never found Doxygen to be so helpful but also have not used it much.
Unlike other languages such as Java, C++ is designed to allow separating
interface from implementation, so better to just use this to being with.
Sphinx seems unnecessarily cryptic to me but serviceable.
On Thu, May 2, 2019 at 10:22 AM Alan Carroll <
solidwallofcode@verizonmedia.com> wrote:
> Yes, although doxylink requires a couple of patches to work well with
> C++17. I have PRs up on the repo for those fixes, but need to find time to
> write some unit tests to get them accepted.
>
> The goal is to have Doxygen generate reference material, while Sphinx
> provides higher level descriptions of the API. Not to mention that when a
> developer goes looking for information, the function/class/method
> definition is usually the first place he checks, and having Doxygen based
> reference information there is a big help.
>
> But who am I to dispute the ATS tradition of undocumented and inscrutable
> API? Nobody else seems to care.
>
> On Thu, May 2, 2019 at 9:25 AM Walt Karas <wk...@verizonmedia.com.invalid>
> wrote:
>
>> Alan do you mean this? https://pythonhosted.org/sphinxcontrib-doxylink/
>>
>> On Thu, May 2, 2019 at 9:21 AM Leif Hedstrom <zw...@apache.org> wrote:
>>
>> >
>> >
>> > > On May 2, 2019, at 08:17, Alan Carroll
>> > <so...@verizonmedia.com.invalid> wrote:
>> > >
>> > > Yes they can work together. I presented on that at the Summit, you
>> should
>> > > have been there.
>> >
>> > I should have.
>> >
>> > So is that setup today? Where does it go? How does it synergize with all
>> > existing API docs?
>> >
>> > And, stop inlining Doxygen comments in function prototypes!!! :-)
>> >
>> > — Leif
>> >
>> >
>> > >
>> > >> On Thu, May 2, 2019 at 9:15 AM Leif Hedstrom <zw...@apache.org>
>> wrote:
>> > >>
>> > >> +1 on docs.
>> > >>
>> > >> However , I think it’s a bit of a mess now with Doxygen sometimes,
>> and
>> > >> normal Sphinx docs (most of the time?). It seems we should have one
>> way
>> > of
>> > >> documenting our interfaces and APIs, no? I find often times, Doxygen
>> can
>> > >> get in the way of code formatting / indentation, specially when
>> > inlined. I
>> > >> really dislike that.
>> > >>
>> > >> It’s probably time to decide. If we decide to go Full R on Doxygen,
>> > >> someone has to shepherd that and start working on it. If not, I
>> think we
>> > >> should drop all Doxygen in favor of just Sphinx. Unless Sphinx and
>> > Doxygen
>> > >> work together in some way that is above my pay grade ?
>> > >>
>> > >> — Leif
>> > >>
>> > >> Found this: https://breathe.readthedocs.io/en/latest/
>> > >>
>> > >>> On May 2, 2019, at 06:19, Alan Carroll
>> > >> <so...@verizonmedia.com.invalid> wrote:
>> > >>>
>> > >>> They shouldn't become invalid during the callback invocation, but
>> may
>> > >> after
>> > >>> the callback returns.
>> > >>>
>> > >>> As for Doxygen, perhaps I am simply weird in that I like to have
>> > >>> documentation for API that I call. I guess I'm just not smart
>> enough to
>> > >>> deduce the meaning and function from only the function and parameter
>> > >> names.
>> > >>
>> >
>> >
>>
>
Re: API Proposal: SSL client context retrieval
Posted by Alan Carroll <so...@verizonmedia.com.INVALID>.
Yes, although doxylink requires a couple of patches to work well with
C++17. I have PRs up on the repo for those fixes, but need to find time to
write some unit tests to get them accepted.
The goal is to have Doxygen generate reference material, while Sphinx
provides higher level descriptions of the API. Not to mention that when a
developer goes looking for information, the function/class/method
definition is usually the first place he checks, and having Doxygen based
reference information there is a big help.
But who am I to dispute the ATS tradition of undocumented and inscrutable
API? Nobody else seems to care.
On Thu, May 2, 2019 at 9:25 AM Walt Karas <wk...@verizonmedia.com.invalid>
wrote:
> Alan do you mean this? https://pythonhosted.org/sphinxcontrib-doxylink/
>
> On Thu, May 2, 2019 at 9:21 AM Leif Hedstrom <zw...@apache.org> wrote:
>
> >
> >
> > > On May 2, 2019, at 08:17, Alan Carroll
> > <so...@verizonmedia.com.invalid> wrote:
> > >
> > > Yes they can work together. I presented on that at the Summit, you
> should
> > > have been there.
> >
> > I should have.
> >
> > So is that setup today? Where does it go? How does it synergize with all
> > existing API docs?
> >
> > And, stop inlining Doxygen comments in function prototypes!!! :-)
> >
> > — Leif
> >
> >
> > >
> > >> On Thu, May 2, 2019 at 9:15 AM Leif Hedstrom <zw...@apache.org>
> wrote:
> > >>
> > >> +1 on docs.
> > >>
> > >> However , I think it’s a bit of a mess now with Doxygen sometimes, and
> > >> normal Sphinx docs (most of the time?). It seems we should have one
> way
> > of
> > >> documenting our interfaces and APIs, no? I find often times, Doxygen
> can
> > >> get in the way of code formatting / indentation, specially when
> > inlined. I
> > >> really dislike that.
> > >>
> > >> It’s probably time to decide. If we decide to go Full R on Doxygen,
> > >> someone has to shepherd that and start working on it. If not, I think
> we
> > >> should drop all Doxygen in favor of just Sphinx. Unless Sphinx and
> > Doxygen
> > >> work together in some way that is above my pay grade ?
> > >>
> > >> — Leif
> > >>
> > >> Found this: https://breathe.readthedocs.io/en/latest/
> > >>
> > >>> On May 2, 2019, at 06:19, Alan Carroll
> > >> <so...@verizonmedia.com.invalid> wrote:
> > >>>
> > >>> They shouldn't become invalid during the callback invocation, but may
> > >> after
> > >>> the callback returns.
> > >>>
> > >>> As for Doxygen, perhaps I am simply weird in that I like to have
> > >>> documentation for API that I call. I guess I'm just not smart enough
> to
> > >>> deduce the meaning and function from only the function and parameter
> > >> names.
> > >>
> >
> >
>
Re: API Proposal: SSL client context retrieval
Posted by Walt Karas <wk...@verizonmedia.com.INVALID>.
Alan do you mean this? https://pythonhosted.org/sphinxcontrib-doxylink/
On Thu, May 2, 2019 at 9:21 AM Leif Hedstrom <zw...@apache.org> wrote:
>
>
> > On May 2, 2019, at 08:17, Alan Carroll
> <so...@verizonmedia.com.invalid> wrote:
> >
> > Yes they can work together. I presented on that at the Summit, you should
> > have been there.
>
> I should have.
>
> So is that setup today? Where does it go? How does it synergize with all
> existing API docs?
>
> And, stop inlining Doxygen comments in function prototypes!!! :-)
>
> — Leif
>
>
> >
> >> On Thu, May 2, 2019 at 9:15 AM Leif Hedstrom <zw...@apache.org> wrote:
> >>
> >> +1 on docs.
> >>
> >> However , I think it’s a bit of a mess now with Doxygen sometimes, and
> >> normal Sphinx docs (most of the time?). It seems we should have one way
> of
> >> documenting our interfaces and APIs, no? I find often times, Doxygen can
> >> get in the way of code formatting / indentation, specially when
> inlined. I
> >> really dislike that.
> >>
> >> It’s probably time to decide. If we decide to go Full R on Doxygen,
> >> someone has to shepherd that and start working on it. If not, I think we
> >> should drop all Doxygen in favor of just Sphinx. Unless Sphinx and
> Doxygen
> >> work together in some way that is above my pay grade ?
> >>
> >> — Leif
> >>
> >> Found this: https://breathe.readthedocs.io/en/latest/
> >>
> >>> On May 2, 2019, at 06:19, Alan Carroll
> >> <so...@verizonmedia.com.invalid> wrote:
> >>>
> >>> They shouldn't become invalid during the callback invocation, but may
> >> after
> >>> the callback returns.
> >>>
> >>> As for Doxygen, perhaps I am simply weird in that I like to have
> >>> documentation for API that I call. I guess I'm just not smart enough to
> >>> deduce the meaning and function from only the function and parameter
> >> names.
> >>
>
>
Re: API Proposal: SSL client context retrieval
Posted by Leif Hedstrom <zw...@apache.org>.
> On May 2, 2019, at 08:17, Alan Carroll <so...@verizonmedia.com.invalid> wrote:
>
> Yes they can work together. I presented on that at the Summit, you should
> have been there.
I should have.
So is that setup today? Where does it go? How does it synergize with all existing API docs?
And, stop inlining Doxygen comments in function prototypes!!! :-)
— Leif
>
>> On Thu, May 2, 2019 at 9:15 AM Leif Hedstrom <zw...@apache.org> wrote:
>>
>> +1 on docs.
>>
>> However , I think it’s a bit of a mess now with Doxygen sometimes, and
>> normal Sphinx docs (most of the time?). It seems we should have one way of
>> documenting our interfaces and APIs, no? I find often times, Doxygen can
>> get in the way of code formatting / indentation, specially when inlined. I
>> really dislike that.
>>
>> It’s probably time to decide. If we decide to go Full R on Doxygen,
>> someone has to shepherd that and start working on it. If not, I think we
>> should drop all Doxygen in favor of just Sphinx. Unless Sphinx and Doxygen
>> work together in some way that is above my pay grade ?
>>
>> — Leif
>>
>> Found this: https://breathe.readthedocs.io/en/latest/
>>
>>> On May 2, 2019, at 06:19, Alan Carroll
>> <so...@verizonmedia.com.invalid> wrote:
>>>
>>> They shouldn't become invalid during the callback invocation, but may
>> after
>>> the callback returns.
>>>
>>> As for Doxygen, perhaps I am simply weird in that I like to have
>>> documentation for API that I call. I guess I'm just not smart enough to
>>> deduce the meaning and function from only the function and parameter
>> names.
>>
Re: API Proposal: SSL client context retrieval
Posted by Alan Carroll <so...@verizonmedia.com.INVALID>.
Yes they can work together. I presented on that at the Summit, you should
have been there.
On Thu, May 2, 2019 at 9:15 AM Leif Hedstrom <zw...@apache.org> wrote:
> +1 on docs.
>
> However , I think it’s a bit of a mess now with Doxygen sometimes, and
> normal Sphinx docs (most of the time?). It seems we should have one way of
> documenting our interfaces and APIs, no? I find often times, Doxygen can
> get in the way of code formatting / indentation, specially when inlined. I
> really dislike that.
>
> It’s probably time to decide. If we decide to go Full R on Doxygen,
> someone has to shepherd that and start working on it. If not, I think we
> should drop all Doxygen in favor of just Sphinx. Unless Sphinx and Doxygen
> work together in some way that is above my pay grade ?
>
> — Leif
>
> Found this: https://breathe.readthedocs.io/en/latest/
>
> > On May 2, 2019, at 06:19, Alan Carroll
> <so...@verizonmedia.com.invalid> wrote:
> >
> > They shouldn't become invalid during the callback invocation, but may
> after
> > the callback returns.
> >
> > As for Doxygen, perhaps I am simply weird in that I like to have
> > documentation for API that I call. I guess I'm just not smart enough to
> > deduce the meaning and function from only the function and parameter
> names.
>
Re: API Proposal: SSL client context retrieval
Posted by Leif Hedstrom <zw...@apache.org>.
+1 on docs.
However , I think it’s a bit of a mess now with Doxygen sometimes, and normal Sphinx docs (most of the time?). It seems we should have one way of documenting our interfaces and APIs, no? I find often times, Doxygen can get in the way of code formatting / indentation, specially when inlined. I really dislike that.
It’s probably time to decide. If we decide to go Full R on Doxygen, someone has to shepherd that and start working on it. If not, I think we should drop all Doxygen in favor of just Sphinx. Unless Sphinx and Doxygen work together in some way that is above my pay grade ?
— Leif
Found this: https://breathe.readthedocs.io/en/latest/
> On May 2, 2019, at 06:19, Alan Carroll <so...@verizonmedia.com.invalid> wrote:
>
> They shouldn't become invalid during the callback invocation, but may after
> the callback returns.
>
> As for Doxygen, perhaps I am simply weird in that I like to have
> documentation for API that I call. I guess I'm just not smart enough to
> deduce the meaning and function from only the function and parameter names.
Re: API Proposal: SSL client context retrieval
Posted by Alan Carroll <so...@verizonmedia.com.INVALID>.
They shouldn't become invalid during the callback invocation, but may after
the callback returns.
As for Doxygen, perhaps I am simply weird in that I like to have
documentation for API that I call. I guess I'm just not smart enough to
deduce the meaning and function from only the function and parameter names.
Re: API Proposal: SSL client context retrieval
Posted by Walt Karas <wk...@verizonmedia.com.INVALID>.
Talked with Zeyuan, he clarified that an example call would be something
like:
const char *ctx[666];
int n_actual_ctx;
rc = TSSslClientContextsGet(666, ctx, &n_actual_ctx);
I don't know enough about SSL to know when the pointers in ctx[] would
become dangling.
On Wed, May 1, 2019 at 2:55 PM Zeyuan Yu <ze...@gmail.com> wrote:
> Alan and Walt pointed out the API needs to be C. Here are the new
> prototypes:
>
> TSReturnCode TSSslClientContextsGet(int n, const char **result, int
> *actual)
> ;
> TSSslContext TSSslClientContextFind(const char *name);
>
>
> [image: work-eat-sleep--400090.jpg]
>
> *Zeyuan Yu*
> Software Development Engineer, Verizon Media Group
>
> work: 217.369.5086
>
> personal: 217.898.1085
>
>
> On Wed, May 1, 2019 at 2:07 PM Zeyuan Yu <ze...@gmail.com> wrote:
>
> >
> > vector<string> TSSslClientContextsGet();
> > TSSslContext TSSslClientContextFind(const string name);
> >
> > ATS has APIs for server context retrieval (TSSslContextFindByName(),
> > TSSslContextFindByAddr()). It would be useful to expose client context
> via
> > APIs too.
> >
> >
> > I would like to propose new APIs for this purpose. Given client context
> > are stored in unordered_map, TSSslClientContextsGet() will return all
> keys
> > (essentially the path to CA/cert files) in a vector;
> > TSSslClientContextFid() will return the context corresponding to the
> input
> > string.
> >
> >
> >
> >
> > [image: work-eat-sleep--400090.jpg]
> >
> > *Zeyuan Yu*
> > Software Development Engineer, Verizon Media Group
> >
> > work: 217.369.5086
> >
> > personal: 217.898.1085
> >
>
Re: API Proposal: SSL client context retrieval
Posted by Zeyuan Yu <ze...@gmail.com>.
Here are the prototypes with comments:
/**
* This function retrieves an array of lookup keys for client contexts
loaded in
* traffic server. Given a 2-level mapping for client contexts, every 2
lookup keys
* can be used to locate and identify 1 context.
* @param n Allocated size for result array.
* @param result Const char pointer arrays to be filled with lookup keys.
* @param actual Total number of lookup keys.
*/
TSReturnCode TSSslClientContextsGet(int n, const char **result, int
*actual);
/**
* This function returns the client context corresponding to the lookup
keys provided.
* User should call TSSslClientContextsGet() first to determine which
lookup keys are
* present before querying for them.
* Returns valid TSSslContext on success and nullptr on failure.
* @param first_key Key string for the top level.
* @param second_key Key string for the second level.
*/
TSSslContext TSSslClientContextFind(const char *first_key, const char
*second_key);
[image: work-eat-sleep--400090.jpg]
*Zeyuan Yu*
Software Development Engineer, Verizon Media Group
work: 217.369.5086
personal: 217.898.1085
On Wed, May 1, 2019 at 4:59 PM Alan Carroll
<so...@verizonmedia.com.invalid> wrote:
> Um, any detail on what the parameters are? Doxygen comments should be the
> minimum provided.
>
> On Wed, May 1, 2019 at 2:55 PM Zeyuan Yu <ze...@gmail.com> wrote:
>
> > Alan and Walt pointed out the API needs to be C. Here are the new
> > prototypes:
> >
> > TSReturnCode TSSslClientContextsGet(int n, const char **result, int
> > *actual)
> > ;
> > TSSslContext TSSslClientContextFind(const char *name);
> >
> >
> > [image: work-eat-sleep--400090.jpg]
> >
> > *Zeyuan Yu*
> > Software Development Engineer, Verizon Media Group
> >
> > work: 217.369.5086
> >
> > personal: 217.898.1085
> >
> >
> > On Wed, May 1, 2019 at 2:07 PM Zeyuan Yu <ze...@gmail.com> wrote:
> >
> > >
> > > vector<string> TSSslClientContextsGet();
> > > TSSslContext TSSslClientContextFind(const string name);
> > >
> > > ATS has APIs for server context retrieval (TSSslContextFindByName(),
> > > TSSslContextFindByAddr()). It would be useful to expose client context
> > via
> > > APIs too.
> > >
> > >
> > > I would like to propose new APIs for this purpose. Given client context
> > > are stored in unordered_map, TSSslClientContextsGet() will return all
> > keys
> > > (essentially the path to CA/cert files) in a vector;
> > > TSSslClientContextFid() will return the context corresponding to the
> > input
> > > string.
> > >
> > >
> > >
> > >
> > > [image: work-eat-sleep--400090.jpg]
> > >
> > > *Zeyuan Yu*
> > > Software Development Engineer, Verizon Media Group
> > >
> > > work: 217.369.5086
> > >
> > > personal: 217.898.1085
> > >
> >
>
Re: API Proposal: SSL client context retrieval
Posted by Walt Karas <wk...@verizonmedia.com.INVALID>.
Doxygen is all that at sign business? Been here almost 2 years first time
I heard it's required. Zwoop did thank me for not doing that.
On Wed, May 1, 2019 at 4:59 PM Alan Carroll
<so...@verizonmedia.com.invalid> wrote:
> Um, any detail on what the parameters are? Doxygen comments should be the
> minimum provided.
>
> On Wed, May 1, 2019 at 2:55 PM Zeyuan Yu <ze...@gmail.com> wrote:
>
> > Alan and Walt pointed out the API needs to be C. Here are the new
> > prototypes:
> >
> > TSReturnCode TSSslClientContextsGet(int n, const char **result, int
> > *actual)
> > ;
> > TSSslContext TSSslClientContextFind(const char *name);
> >
> >
> > [image: work-eat-sleep--400090.jpg]
> >
> > *Zeyuan Yu*
> > Software Development Engineer, Verizon Media Group
> >
> > work: 217.369.5086
> >
> > personal: 217.898.1085
> >
> >
> > On Wed, May 1, 2019 at 2:07 PM Zeyuan Yu <ze...@gmail.com> wrote:
> >
> > >
> > > vector<string> TSSslClientContextsGet();
> > > TSSslContext TSSslClientContextFind(const string name);
> > >
> > > ATS has APIs for server context retrieval (TSSslContextFindByName(),
> > > TSSslContextFindByAddr()). It would be useful to expose client context
> > via
> > > APIs too.
> > >
> > >
> > > I would like to propose new APIs for this purpose. Given client context
> > > are stored in unordered_map, TSSslClientContextsGet() will return all
> > keys
> > > (essentially the path to CA/cert files) in a vector;
> > > TSSslClientContextFid() will return the context corresponding to the
> > input
> > > string.
> > >
> > >
> > >
> > >
> > > [image: work-eat-sleep--400090.jpg]
> > >
> > > *Zeyuan Yu*
> > > Software Development Engineer, Verizon Media Group
> > >
> > > work: 217.369.5086
> > >
> > > personal: 217.898.1085
> > >
> >
>
Re: API Proposal: SSL client context retrieval
Posted by Alan Carroll <so...@verizonmedia.com.INVALID>.
Um, any detail on what the parameters are? Doxygen comments should be the
minimum provided.
On Wed, May 1, 2019 at 2:55 PM Zeyuan Yu <ze...@gmail.com> wrote:
> Alan and Walt pointed out the API needs to be C. Here are the new
> prototypes:
>
> TSReturnCode TSSslClientContextsGet(int n, const char **result, int
> *actual)
> ;
> TSSslContext TSSslClientContextFind(const char *name);
>
>
> [image: work-eat-sleep--400090.jpg]
>
> *Zeyuan Yu*
> Software Development Engineer, Verizon Media Group
>
> work: 217.369.5086
>
> personal: 217.898.1085
>
>
> On Wed, May 1, 2019 at 2:07 PM Zeyuan Yu <ze...@gmail.com> wrote:
>
> >
> > vector<string> TSSslClientContextsGet();
> > TSSslContext TSSslClientContextFind(const string name);
> >
> > ATS has APIs for server context retrieval (TSSslContextFindByName(),
> > TSSslContextFindByAddr()). It would be useful to expose client context
> via
> > APIs too.
> >
> >
> > I would like to propose new APIs for this purpose. Given client context
> > are stored in unordered_map, TSSslClientContextsGet() will return all
> keys
> > (essentially the path to CA/cert files) in a vector;
> > TSSslClientContextFid() will return the context corresponding to the
> input
> > string.
> >
> >
> >
> >
> > [image: work-eat-sleep--400090.jpg]
> >
> > *Zeyuan Yu*
> > Software Development Engineer, Verizon Media Group
> >
> > work: 217.369.5086
> >
> > personal: 217.898.1085
> >
>
Re: API Proposal: SSL client context retrieval
Posted by Zeyuan Yu <ze...@gmail.com>.
Alan and Walt pointed out the API needs to be C. Here are the new
prototypes:
TSReturnCode TSSslClientContextsGet(int n, const char **result, int *actual)
;
TSSslContext TSSslClientContextFind(const char *name);
[image: work-eat-sleep--400090.jpg]
*Zeyuan Yu*
Software Development Engineer, Verizon Media Group
work: 217.369.5086
personal: 217.898.1085
On Wed, May 1, 2019 at 2:07 PM Zeyuan Yu <ze...@gmail.com> wrote:
>
> vector<string> TSSslClientContextsGet();
> TSSslContext TSSslClientContextFind(const string name);
>
> ATS has APIs for server context retrieval (TSSslContextFindByName(),
> TSSslContextFindByAddr()). It would be useful to expose client context via
> APIs too.
>
>
> I would like to propose new APIs for this purpose. Given client context
> are stored in unordered_map, TSSslClientContextsGet() will return all keys
> (essentially the path to CA/cert files) in a vector;
> TSSslClientContextFid() will return the context corresponding to the input
> string.
>
>
>
>
> [image: work-eat-sleep--400090.jpg]
>
> *Zeyuan Yu*
> Software Development Engineer, Verizon Media Group
>
> work: 217.369.5086
>
> personal: 217.898.1085
>