Skip to content

Separate root path for invocation-specific JS #1851

Open
@jsha

Description

@jsha

This is really a cross-team issue for rustdoc and docs-rs, but I figure this is the better repo to discuss on. /cc @rust-lang/rustdoc

Steps to reproduce (hypothetical, haven't manually tested):

  1. Release version 1.0.0 of crate_foo.
  2. Visit https://docs.rs/crate_foo/latest/crate_foo/ and leave it open in a browser tab.
  3. Wait for the next nightly release.
  4. Release version 1.0.1 of crate_foo (and wait for docs to build).
  5. In that browser tab, click the search box and search for an item.

I believe this will fail to load the search, because the HTML that was sitting in that browser tab expected to load, e.g. https://docs.rs/crate_foo/latest/search-index-20220918-1.66.0-nightly-a37499ae6.js, but that URL no long exists; in its place is something like https://docs.rs/crate_foo/latest/search-index-20220919-1.66.0-nightly-712a6c5a.js (that is, the search index for version 1.0.1, generated by the next day's nightly).

I think this could be fixed by loading all invocation-specific JS from an explicitly versioned URL, even when the HTML is loaded from a /latest/ URL. For instance, if the search index was loaded from https://docs.rs/crate_foo/1.0.0/search-index-20220918-1.66.0-nightly-a37499ae6.js, this would continue to work even when a browser tab is held open across releases.

This would necessitate a new rustdoc flag, by analogy with --static-root-path, maybe --invocation-specific-js-root-path. docs.rs would pass this flag with a URL that points to the explicitly versioned URL for the crate being built.

We could also decide the problem isn't worth fixing. I think this is only a real problem for the search index. The other invocation-specific files (sidebar-items, crates, trait implementors) are loaded on page load so they're not an issue. And presumably a user faced with a broken search bar would simply reload.

However, note that this would also solve #1593. Or, we could solve #1593 (but not this issue) by amending the resource suffix for invocation-specific files to also include the crate version.

Related to #1552.

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions