Subject: [Tools-discuss] How do we diagnose DOI errors?

From: "Martin Thomson" <[email-masked]>
Date: Mon, 19 Oct 2020 12:58:44 +1100

https://xml2rfc.tools.ietf.org/public/rfc/bibxml7/reference.DOI.10.1145/357401.357402.xml returns 404.  It did not used to.

https://xml2rfc.tools.ietf.org/public/rfc/bibxml7/reference.DOI.10.6028_NIST.FIPS.180-4.xml is fine.

I've come to rely on this mechanism for citing documents, but it isn't good if it isn't reliable.  Some better information about how this operates would be great.

---

From: "Martin Thomson" <[email-masked]>
Date: Mon, 19 Oct 2020 14:10:20 +1100

As someone pointed out to me, this is now working again.  The original question stands.

On Mon, Oct 19, 2020, at 12:58, Martin Thomson wrote:
> I've come to rely on this mechanism for citing documents, but it isn't 
> good if it isn't reliable.  Some better information about how this 
> operates would be great.
> 
> ___________________________________________________________
> Tools-discuss mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/tools-discuss
> 
> Please report datatracker.ietf.org and mailarchive.ietf.org
> bugs at http://tools.ietf.org/tools/ietfdb
> or send email to [email-masked]
> 
> Please report tools.ietf.org bugs at
> http://tools.ietf.org/tools/issues
> or send email to [email-masked]
>

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 19 Oct 2020 07:39:37 +0200

> I've come to rely on this mechanism for citing documents, but it isn't good if it isn't reliable.  Some better information about how this operates would be great.

As far as I understand, the DOI bibxml is based on the doilit tool that is part of kramdown-rfc2629 (which in turn is using https://dx.doi.org/).  A 24-h cache helps keeping the load down but the data reasonably fresh.  As far as I can see, all kinds of errors are mapped to 404.

One tweak that can help coping with doi.org outages might be keeping the cache indefinitely.  Freshness could still be achieved by *trying* to get a refresh after 24 h, but keeping the cached value in place if that fails for some reason.

Grüße, Carsten

---

From: "Martin Thomson" <[email-masked]>
Date: Mon, 19 Oct 2020 17:19:34 +1100

On Mon, Oct 19, 2020, at 16:39, Carsten Bormann wrote:
> As far as I understand, the DOI bibxml is based on the doilit tool that 
> is part of kramdown-rfc2629 (which in turn is using 
> https://dx.doi.org/).  A 24-h cache helps keeping the load down but the 
> data reasonably fresh.  As far as I can see, all kinds of errors are 
> mapped to 404.
> 
> One tweak that can help coping with doi.org outages might be keeping 
> the cache indefinitely.  Freshness could still be achieved by *trying* 
> to get a refresh after 24 h, but keeping the cached value in place if 
> that fails for some reason.

That seems like a reasonable enhancement.  These outages are far to frequent for my liking.  This is hardly the first occurrence.

You can tune the timeout right down at the same time; these rarely change and anyone who uses these often (through CI, for instance) will ensure that they are kept fresh enough.  (stale-while-revalidate...)

You might need to consider whether or not the cache needs an occasional flush to avoid unbounded accumulation of old entries.

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 19 Oct 2020 08:45:03 +0200

> On 2020-10-19, at 08:19, Martin Thomson <[email-masked]> wrote:
> 
> 

Indeed, the reason kramdown-rfc doesn’t do the processing entirely on its own was to take advantage of the cache at ietf.org to improve availability.

> You can tune the timeout right down at the same time; these rarely change and anyone who uses these often (through CI, for instance) will ensure that they are kept fresh enough.  (stale-while-reval…

Exactly.

> You might need to consider whether or not the cache needs an occasional flush to avoid unbounded accumulation of old entries.

I don’t think so; the number of DOIs in existence is sufficiently limited (unless we try to do negative caching, but I see no point in that).

Grüße, Carsten

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 19 Oct 2020 08:46:58 +0200

> As far as I understand, the DOI bibxml is based on the doilit tool that is part of kramdown-rfc2629 (which in turn is using https://dx.doi.org/).  A 24-h cache helps keeping the load down but the d…

(Which, I forgot to say, means that the answer to the question in the subject is to run the doilit tool locally for extended diagnostics.)

Grüße, Carsten

---

From: Michael Richardson <[email-masked]>
Date: Mon, 19 Oct 2020 10:57:24 -0400

> As someone pointed out to me, this is now working again.  The original

10.1145 works for me today using the link you listed.
I had the same problem last weekend.  Very annoying.
I could wget things from /rfc/bibxml/FOO, but not /rfc/bibxmlX/FOO.

How do you typically use the URLs?
In ENTITY statements, via <?rfc include=, or does kramdown generate things?
I think that ENTITY statements are the least portable, and should be
discouraged to the point of having warnings from xml2rfc.

Given that the contents are are static and are rsync'able, and I don't see
why they shouldn't be replicated widely.   An annoyance is that xml2rfc won't
use the local copy if the network copy returns 404, unless you specify --no-network,
which naturally only works if you already have *all* the references.

You can set $XML_LIBRARY to a path, and I think also set it to a URL.
At least you could, but I don't know if I've done this lately.

I also see, but maybe this doesn't do what I think:
  --rfc-base-url RFC_BASE_URL
                        Base URL for RFC links
  --id-base-url ID_BASE_URL
                        Base URL for Internet-Draft links
  --rfc-reference-base-url RFC_REFERENCE_BASE_URL
                        Base URL for RFC reference targets, replacing the
                        target="..." value given in the reference entry
  --id-reference-base-url ID_REFERENCE_BASE_URL
                        Base URL for I-D reference targets

    > returns 404.  It did not used to.

At this point, xmlrfc.ietf.org redirects to xml2rfc.tools.ietf.org.
I thought that we were trying to bring tools into secretariat supported
hosts, and this certainly seems like low hanging fruit.

--
Michael Richardson <[email-masked]>   . o O ( IPv6 IøT consulting )
           Sandelman Software Works Inc, Ottawa and Worldwide

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 19 Oct 2020 17:57:28 +0200

> discouraged to the point of having warnings from xml2rfc.

Kramdown-rfc has two modes:
It can generate entity declarations and entity references (stand_alone: false — the default), relying on xml2rfc to do the insertions.
It can simply insert the referenced items itself (stand_alone: true).

stand_alone: true is the preferred setting, as kramdown-rfc can do some gymnastics on the anchors; not all kramdown-rfc features work with entity declarations and references.

xml2rfc can also do resolution via PIs and via xinclude elements; kramdown-rfc cannot generate these two syntaxes (but of course you can type in the XML).

> why they shouldn't be replicated widely.  

Replicating “they” won’t work for DOI references, as anybody can bring a new DOI and bibxml7 automatically builds the bibliography information from the doi.org.
The cache for that lives in /var/tmp/doi-cache, which cannot be rsynced from the bibxml server.
(Except for the IANA references in bibxml8, which are also auto-generated and held in /var/tmp/iana-cache, the rest of bibxml can be.)
I sometimes copy reference files from my rsync copy to ~/.cache/xml2rfc (I also tell kramdown-rfc to use the same cache via

export KRAMDOWN_REFCACHEDIR=/Users/cabo/.cache/xml2rfc

> An annoyance is that xml2rfc won't

I’m not sure about xml2rfc’s cache behavior.
With kramdown-rfc, existing cache files, even if stale, will be used after a refresh timeout.
With KRAMDOWN_OFFLINE, kramdown-rfc will generate dummy references for you if there are no cache files, which can be great if you want to submit and are just held up by a missing reference.

>                        Base URL for I-D reference targets

(I think I need to document the equivalent kramdown-rfc parameters XML_RESOURCE_ORG_HOST and XML_RESOURCE_ORG_PREFIX.)
Kramdown-rfc cannot get the I-Ds from a different place than the other references; with the datatracker support for I-D bibxml, this is one of the next features to be put in.

> At this point, xmlrfc.ietf.org redirects to xml2rfc.tools.ietf.org.

The redirect would be another SPOF…
Therefore the default parameters in kramdown-rfc are:
XML_RESOURCE_ORG_HOST: "xml2rfc.tools.ietf.org”
XML_RESOURCE_ORG_PREFIX: "https://#{XML_RESOURCE_ORG_HOST}/public/rfc"

> hosts, and this certainly seems like low hanging fruit.

As soon as this actually is secretariat supported software, that certainly will make sense.

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Mon, 19 Oct 2020 18:18:09 +0200

Am 19.10.2020 um 16:57 schrieb Michael Richardson:
> ...

How so? They are an integral part of XML.

Best regards, Julian

---

From: Michael Richardson <[email-masked]>
Date: Mon, 19 Oct 2020 13:40:49 -0400

> How so? They are an integral part of XML.

If you use a specific URL, then it needs to be alive.
While many of the other abstractions can be retrieved from a variety of
sources and can be easily cached.

I suspect that there are smarter things you can put into the ENTITY,
I don't know how to do it, and I think neither do many other people.

---

From: Julian Reschke <[email-masked]>
Date: Mon, 19 Oct 2020 20:17:15 +0200

> If you use a specific URL, then it needs to be alive.

Yes.

But I would call that "robustness", not "portability".

> sources and can be easily cached.

Hmm, no. All the ones that are defined for xml2rfc v3 need a full URI,
and all of them can be cached.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 19 Oct 2020 20:51:17 +0200

On 2020-10-19, at 20:17, Julian Reschke <[email-masked]> wrote:
> 
> All the ones that are defined for xml2rfc v3 need a full URI,

… which can get in the way of implementing more robustness in the tools for many-sourced information.
(Until we define special URIs for that…)

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Mon, 19 Oct 2020 21:38:21 +0200

> (Until we define special URIs for that…)

We could do that, or just make sure that the URIs that we use are indeed
robust. Or just avoid include-by-reference (my preference).

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Mon, 19 Oct 2020 21:46:53 +0200

On 2020-10-19, at 21:38, Julian Reschke <[email-masked]> wrote:
> 
>  Or just avoid include-by-reference (my preference).

I know that is your preference, but most authors do find a reference that evaluates to the most current version of the document being referenced very convenient for their own documents, which tend to live for several years before being published.

(On the publishing side, of course DO avoid include-by-reference, I’m talking about the authoring side.)

Grüße, Carsten

---

From: Michael Richardson <[email-masked]>
Date: Mon, 19 Oct 2020 16:42:32 -0400

> But I would call that "robustness", not "portability".

I plug in

      <?rfc include="reference.RFC.8174" ?>

and the tool figures out where to get the data.

When I do:

<!ENTITY RFC2119 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml">

then I'm being very specific, and if the site breaks, or produces 404s for
some reason, then things break for me.
(Yes, I have a document with one of each. Too lazy to change)

    > and all of them can be cached.

My dated experience with caching all of bibxml to my laptop so that I could
compose on long airplane flights was that the ENTITY mechanism never worked
right.  That's probably a bug, but and maybe I'm cargo culting, but that's
why I've come to prefer <?rfc.  if I have to author in XML.
{which I strongly prefer not to now}

--
]               Never tell me the odds!                 | ipv6 mesh networks [
]   Michael Richardson, Sandelman Software Works        |    IoT architect   [
]     [email-masked]  http://www.sandelman.ca/        |   ruby on rails    [

---

From: Julian Reschke <[email-masked]>
Date: Tue, 20 Oct 2020 06:01:01 +0200

> and the tool figures out where to get the data.

But that's not part of the official xml2rfc vocabulary.

> some reason, then things break for me.

The tool *can* cache it the same way. This helps when the site is
unreachable, but of course not when it removes the document. Which it
should not.

We really should have a reliable place for the reference information. I
still don't get why we recommended the above URI back in RFC 7749 (I
*think* after consuting with the RPC), and now that redirects to
tools.ietf.org.

Best regards, Julian

---

From: Carsten Bormann <[email-masked]>
Date: Tue, 20 Oct 2020 08:13:46 +0200

> On 2020-10-20, at 06:01, Julian Reschke <[email-masked]> wrote:
> 
>> <!ENTITY RFC2119 SYSTEM "https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml”>
> […]

I don’t think RFC 7749 “recommended” that URI; it just used a similar URI in an example for declaring and using an external entity.

Kramdown-rfc briefly used xml2rfc.ietf.org; I don’t recollect exactly why we switched back to xml2rfc.tools.ietf.org as suggested in RFC 7991; I seem to remember that this was to avoid the redirect from xml2rfc.ietf.org to xml2rfc.tools.ietf.org and the attendant SPOF and delay.  After all, xml2rfc.ietf.org continues to say 301 Moved Permanently:

$ curl -I https://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml
HTTP/1.1 301 Moved Permanently
Date: Tue, 20 Oct 2020 06:02:05 GMT
Server: Apache
Location: https://xml2rfc.tools.ietf.org/public/rfc/bibxml/reference.RFC.2119.xml
Content-Type: text/html; charset=iso-8859-1
$ 

I believe that the interface to the canned bibliography information needs to be an integral part of the authoring side of RFCXML, but tools-discuss is the wrong mailing list for that discussion (or is it?).

(Here is the text from RFC 7991 Appendix B.1:

   The most common way to use <xi:include> is to pull in references that
   are already formed as XML.  Currently, this can be done from
   xml2rfc.tools.ietf.org, but later this is expected to be from the RFC
   Editor.

I don’t know who owns the authoring side of RFCXML; if it is the RFC Editor, it might indeed seem logical for this responsibility to rest with the RPC.)

Grüße, Carsten

---

From: Julian Reschke <[email-masked]>
Date: Tue, 20 Oct 2020 10:10:47 +0200

> I don’t think RFC 7749 “recommended” that URI; it just used a similar URI in an example for declaring and using an external entity.

That is true. But when we published this, we made sure that this is
actually the URI the RPC wanted us to use.

> Kramdown-rfc briefly used xml2rfc.ietf.org; I don’t recollect exactly why we switched back to xml2rfc.tools.ietf.org as suggested in RFC 7991; I seem to remember that this was to avoid the redirect…

Yes. Until recently it was a 302, but I asked to make that a 301 so the
response can be cached more agressively.

> I don’t know who owns the authoring side of RFCXML; if it is the RFC Editor, it might indeed seem logical for this responsibility to rest with the RPC.)

...at least for RFC references. Yes.

Best regards, Julian

---

From: Michael Richardson <[email-masked]>
Date: Tue, 20 Oct 2020 11:11:45 -0400

> But that's not part of the official xml2rfc vocabulary.

As long as I can submit RFCs to the RFC-editor with this syntax, and it
passes idnits, etc., then I think it is part of the xml2rfc vocabulary, and
the official document might be wrong :-)
(PS vs IS)

I know that this is a source of dispute.
I don't know how we are going to fix this.