block_content routes have ambiguous paths

Question

I'm trying to convert block forms (the content entity forms) into Gin Admin theme forms. Gin theme provides a hook for this:

function hook_gin_content_form_routes(): array {
  return [
    'entity.block_content.edit_form',
    'block_content.add_form',
  ];
}

This worked fine for new blocks (add_form), but it did not work for existing blocks (edit_form). After digging around, I found out that the content block edit form actually does not use this route. Instead the debugger told me the route name is entity.block_content.canonical. And digging in core's block_content.routing.yml I found two routes with ambiguous path names and parameters:

entity.block_content.canonical:
  path: '/block/{block_content}'
  defaults:
    _entity_form: 'block_content.edit'
  options:
    _admin_route: TRUE
  requirements:
    _entity_access: 'block_content.update'
    block_content: \d+

entity.block_content.edit_form:
  path: '/block/{block_content}'
  defaults:
    _entity_form: 'block_content.edit'
  options:
    _admin_route: TRUE
  requirements:
    _entity_access: 'block_content.update'
    block_content: \d+

While adding entity.block_content.canonical solved my problem, I don't understand what's going on here.

First, how can one path with identical options and parameters be part of 2 different routes? Isn't the 2nd route just dead weight?

And why is a canonical route used for editing? I thought canonical routes are meant to be used for frontend/view display, not for admin forms (e.g. entity.node.canonical and similar).

I'm asking those two questions because I am afraid of unintented side effects when adding a canonical route to Gin's form preprocessing.

Answer 1

First, you can define multiple routes for the same path. If more than one route matches the path the route is selected using different criteria like access, protocol, format, fit (the number of fixed path elements) or the alphabetical order of the route names.

And then, a block doesn't have a view route. Drupal duplicated the edit route so that they don't get errors from code expecting all entities to have a default aka canonical route. It's safe to add both routes to Gin. See https://www.drupal.org/project/drupal/issues/2873529

Answer 2

This acts like an alias - two routes to the same path. Routes are allowed to share paths. As Block Content, which are content entities, don't actually have a display page, the canonical link for the Block Content is set as the edit form. The edit form is also set as the edit form, because it's the edit form! If there was no canonical path for the block, scripts that loop through entity types and output their links would have a fatal error, so creating a canonical route standardizes block content to be able to be used in scripts the same as other content entities.