mikrotik-mcp: 31 modules regrouped into 12 feature areas

1 day ago

Pull request 224 in wiresage/mikrotik-mcp regroups the 31 tool modules of scope/ into 12 feature-area packages, with tests and reference pages following the same layout. Tool names, parameters and commands do not change. The video covers the new layout, how a module registers, the evidence that nothing changed, the layout tests, the review fixes and what open pull requests need to do.

Ask about this presentation

Chapters

  1. 0:00One folder of 31 modules becomes 12 feature areas
  2. 0:22Finding a tool meant scanning one long folder
  3. 0:44Now each feature area is its own package
  4. 1:14A module registers its tools by being imported
  5. 1:38The tool catalogue is identical to master
  6. 2:09Live runs on two routers match the previous release
  7. 2:35Layout tests keep the structure from decaying
  8. 2:59Review found guards that could pass while checking nothing
  9. 3:27What to know before you rebase
  10. 3:56A new tool now starts in its area
Show transcript
  1. Every tool in this server used to live in one folder. This change sorts them into twelve feature areas, and the tests and reference pages move with them. A model or a user sees no difference: the same tool names, the same parameters, the same RouterOS commands. What changes is where everything lives, and that is why it is worth a few minutes.

    Slide text
    refactor · scope/

    Same tools, same parameters, same RouterOS commands.

    Pull request #224

  2. Before, scope was a single folder with thirty one tool modules and three helpers side by side. Firewall sat next to scheduler, and backup sat next to wireless. The app file imported all of them on one line, and the smoke test kept a hand written list that had already forgotten two modules. Issue 222 asked for one package per feature area.

    Slide text
    scope/ 31 tool modules 3 helpers one import line in app.py
  3. Firewall holds six modules, and interfaces holds six more. IP has five, and system has the info, scheduler and backup tools. Monitoring gathers logs, Netwatch and the diagnostics tools, because they all observe a device. The author says that placement is easy to change. Devices holds the inventory and safe mode. DHCP, DNS, routing, queues, users and VPN have one module each, and helpers shared by several areas live in an underscore shared package.

    Slide text
    firewall 6 filter · ipv6_filter · nat · raw · ipv6_raw · address_list
    interfaces 6 generic · vlan · bridge · wireguard · wireless · poe
    ip 5 address · ipv6_address · pool · neighbors · services
    system 3 info · scheduler · backup
    monitoring 3 logs · netwatch · diagnostics
    devices 2 inventory · safe_mode
    dhcp dns routing queue users vpn 6 one module each
    _shared 2 quoting · selectors
  4. Each area has an init file with a one line charter and a list like this one. Importing a module is what registers its tools, so app.py now imports twelve packages, one per line, instead of thirty one modules on one line. The catch is that a module missing from this list registers nothing and fails quietly. That is why the layout tests check every area against its folder.

    Slide text
    from . import (
        address_list,
        filter,
        ipv6_filter,
        ipv6_raw,
        nat,
        raw,
    )

    firewall/__init__.py · one module per line

  5. The author compared the tool catalogue against master in all three modes. The default server exposes 239 tools, read only mode exposes 107, and sensitive hiding mode matches too. Only the registration order differs. Every tool function, 233 of them, builds the same 570 RouterOS commands and returns the same text. Unit tests grew from 1040 to 1194 cases, and the additions are the new guards.

    Slide text
    239 tools, default mode
    107 tools, read-only
    570 commands, byte for byte

    Names, titles, descriptions, schemas and annotations compared in source and in the built wheel.

  6. The wheel built from this branch also ran against two lab routers. Read only mode passed every one of its 223 steps. The main pass passed 495 of 534. The author reports that the steps that fail also fail on the previous release, 0.28.1.0, and traces them to known tool defects, not to the move. So the move adds no new failures.

    Slide text
    223 / 223 read-only steps
    495 / 534 main pass steps

    The remaining failures also appear on 0.28.1.0.

  7. A move like this can slowly come undone, so the pull request adds tests for the rules. The app file must import every area. Each area must import every module in its folder. Areas never import each other, and shared code goes in the shared package. Every tool module needs its reference page. The author broke the layout on purpose thirteen ways and watched the right test fail each time.

    Slide text
    • app.py imports every area
    • each area imports every module in it
    • areas never import each other
    • every tool module has a reference page
  8. The reviewer, inistor, found that several of the new guards could pass without checking anything. A hasattr check could let a tool reach the real SSH connector, so every module is now patched strictly. Link checks used substring matches, so a dropped filter link hid behind the ipv6 filter link. They now compare parsed targets. A leftover cache folder no longer counts as a package, and a nested sub-folder is rejected. The reviewer broke each guard on purpose and approved.

    Slide text
    hasattr guard in the smoke test every module patched strictly
    substring match on page links link targets parsed and compared
    leftover __pycache__ counted as a package only folders with Python files count
    nested sub-folders unchecked areas must be flat
  9. The description lists what to expect. Every open pull request that touches the scope folder needs a rebase. Edits to moved files follow the renames, and the conflicts are mostly the import block at the top of each file. There are no compatibility imports, because nothing outside this repository imports these modules. The contributing page in the website repository still describes the old layout and needs a follow up. And old links to the moved reference pages no longer resolve.

    Slide text
    • Open pull requests that touch scope/ need a rebase
    • No backward-compatible imports
    • The website contributing page still shows the old layout
    • Old reference page URLs no longer exist
  10. The merge releases a patch version, and that is the one limit to keep in mind: the structure is new, and the website still needs its follow up. From now on, a new tool module goes in the package of its area and in that area's import list. If you forget, the layout test says exactly what to move or import. One folder of thirty one modules is now twelve feature areas.

    Slide text

    Add the module to the area's __init__.py, and the layout test tells you if you forget.

    Pull request #224 · closes #222

What happened in AI today, in your inbox

One short email each evening. Read it and you’re caught up.

Built with ❤️ in New York