toolforge

The toolforge crate provides helper functions for various tasks on Toolforge.

See wikitech for the full documentation.

License

toolforge is (C) 2013, 2017, 2020-2021 Kunal Mehta, released under the GPL v3 or any later version, see COPYING for details.

lib.rs:

The toolforge crate provides helper functions for various tasks on Toolforge.

Constructing a User-Agent

The user_agent! macro generates a tool-specific User-Agent header in compliance with Wikimedia's User-Agent policy. The first and only required parameter is the tool's name. Optional second and third parameters can be overrides to the url and email, respectively.

Example

const USER_AGENT: &str = toolforge::user_agent!("mycooltool");

assert_eq!(
    USER_AGENT,
    "https://mycooltool.toolforge.org/ tools.mycooltool@toolforge.org"
);

WikiReplica connection helpers

The connection_info! macro builds the URL string to connect to Wiki Replicas for use with the mysql_async crate. It should also work with the mysql crate. Specifically, it follows the Toolforge connection handling policy.

The first argument is the database name, with or without a _p suffix. The second (optional) argument is which cluster to connect to, either WEB (default) or ANALYTICS.

Example

use mysql_async::Pool;
let pool = Pool::new(
    toolforge::connection_info!("enwiki", WEB)
        .expect("unable to load db config")
        .to_string()
        .as_str(),
);
let mut conn = pool.get_conn().await?;

Local development

Copy your tool's replica.my.cnf to your local machine, saving it to ~/replica.my.cnf and add a local='true' flag. For example:

[client]
user='u####'
password='...'
local='true'

Then open a SSH tunnel on port 3306 to the specific wiki replicas database you want to access. The toolforge-tunnel helper described below can simplify this.

WikiPool feature

WikiPool is a wrapper around mysql_async::Pool that given a database name, will connect to the appropriate backend server. It is smart enough to know which databases are on the same server so connections can be optimally reused for better performance. This is behind the wikipool feature.

toolforge-tunnel helper

The toolforge-tunnel tool simplifies the process of opening SSH tunnels to wiki replicas. Example usage: toolforge-tunnel enwiki.

It can be installed via cargo: cargo install toolforge --features=cli. Pre-built binaries can be downloaded from GitLab.

Contributing

toolforge is a part of the mwbot-rs project. We're always looking for new contributors, please reach out if you're interested!