Struct veloren_server::settings::banlist::Banlist

pub struct Banlist {
    pub(super) uuid_bans: HashMap<Uuid, BanEntry>,
    pub(super) ip_bans: HashMap<NormalizedIpAddr, IpBanEntry>,
}

NOTE: Always replace this with the latest banlist version. Then update the BanlistRaw, the TryFrom for Banlist, the previously most recent module, and add a new module for the latest version! Please respect the migration upgrade guarantee found in the parent module with any upgrade.

Fields

uuid_bans: HashMap<Uuid, BanEntry>

ip_bans: HashMap<NormalizedIpAddr, IpBanEntry>

Implementations

impl Banlist

pub fn uuid_bans(&self) -> &HashMap<Uuid, BanEntry>

pub fn ip_bans(&self) -> &HashMap<NormalizedIpAddr, IpBanEntry>

pub fn ban_operation( &mut self, data_dir: &Path, now: DateTime<Utc>, uuid: Uuid, username_when_performed: String, operation: BanOperation, overwrite: bool, ) -> Result<Option<BanInfo>, BanOperationError>

Attempt to perform the ban operation operation for the user with UUID uuid and username username, starting from time now (the information about the banning party will be in the operation record), with a settings file maintained at path root data_dir.

Banning an IP via a user will also ban that user’s UUID. Additionally, a regular UUID unban will also produce an IP unban if a corresponding one is active and linked to the unbanned UUID.

If trying to unban an already unbanned player, or trying to ban but the ban status would not immediately change, the “overwrite” boolean should also be set to true.

We try to detect duplicates (bans that would have no effect) and return Err(BanOperationError::NoEffect) if such effects are encountered.

If the errors outlined above are successfully avoided, we attempt the edit either succeeding and returning Ok(()) or returning Err(BanOperationError::EditFailed(error)), which works as follows.

If the ban was invalid for any reason, then neither the in-memory banlist nor the on-disk banlist are modified. If the ban entry is valid but the file encounters an error that prevents it from being atomically written to disk, we return an error but retain the change in memory. Otherwise, we complete successfully and atomically write the banlist to disk.

Note that the IO operation is only guaranteed atomic in the weak sense that either the whole page is written or it isn’t; we cannot guarantee that the data we read in order to modify the file was definitely up to date, so we could be missing information if the file was manually edited or a function edits it without going through the usual specs resources. So, please be careful with ad hoc modifications to the file while the server is running.

fn apply_ban_record( &mut self, uuid: Uuid, record: BanRecord, overwrite: bool, now: DateTime<Utc>, ) -> Option<()>

Only meant to be called by Self::ban_operation within the edit closure.

Returns None to cancel early and abandon the edit.

fn apply_ip_ban_record( &mut self, ip: NormalizedIpAddr, record: IpBanRecord, overwrite: bool, now: DateTime<Utc>, ) -> Option<()>

Only meant to be called by Self::ban_operation within the edit closure.

Returns None to cancel early and abandon the edit.

pub(super) fn migrate(prev: Banlist) -> Self

One-off migration from the previous version. This must be guaranteed to produce a valid settings file as long as it is called with a valid settings file from the previous version.

pub(super) fn validate( &mut self, ) -> Result<Version, <Banlist as EditableSetting>::Error>

Perform any needed validation on this banlist that can’t be done using parsing.

The returned version being “Old” indicates the loaded setting has been modified during validation (this is why validate takes &mut self).

Trait Implementations

impl Clone for Banlist

fn clone(&self) -> Banlist

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Default for Banlist

fn default() -> Banlist

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Banlist

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl EditableSetting for Banlist

type Error = BanError

Please use this error sparingly, since we ideally want to preserve forwards compatibility for all migrations. In particular, this error should be used to fail validation of the original settings file that cannot be caught with ordinary parsing, rather than used to signal errors that occurred during migrations.

type Legacy = Banlist

Into is expected to migrate directly to the latest version, which can be implemented using “chaining”. The use of Into here rather than TryInto is intended (together with the expected use of chaining) to prevent migrations from invalidating old save files without warning; there should always be a non-failing migration path from the oldest to latest format (if the migration path fails, we can panic).

type Setting = BanlistRaw

TryInto<(Version, Self)> is expected to migrate to the latest version from any older version, using “chaining” (see super::banlist for examples).

const FILENAME: &'static str = FILENAME

fn load(data_dir: &Path) -> Self

fn edit<R>( &mut self, data_dir: &Path, f: impl FnOnce(&mut Self) -> Option<R>, ) -> Option<(R, Result<(), Error<Self>>)>

If the result of calling f is None, we return None (this constitutes an early return and lets us abandon the in-progress edit). For example, this can be used to avoid adding a new ban entry if someone is already banned and the user didn’t explicitly specify that they wanted to add a new ban record, even though it would be completely valid to attach one.

fn get_path(data_dir: &Path) -> PathBuf

impl From<Banlist> for Banlist

fn from(value: Banlist) -> Self

Legacy migrations can be migrated to the latest version through the process of “chaining” migrations, starting from next::Banlist.

Note that legacy files are always valid, which is why we implement From rather than TryFrom.

impl From<Banlist> for BanlistRaw

fn from(value: Banlist) -> Self

Converts to this type from the input type.

impl Serialize for Banlist

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl TryFrom<Banlist> for Banlist

type Error = <Banlist as EditableSetting>::Error

The type returned in the event of a conversion error.

fn try_from(value: Banlist) -> Result<Banlist, Self::Error>

Performs the conversion.

impl TryFrom<Banlist> for Banlist

Pretty much every TryFrom implementation except that of the very last version should look exactly like this.

type Error = <Banlist as EditableSetting>::Error

The type returned in the event of a conversion error.

fn try_from(value: Banlist) -> Result<Banlist, Self::Error>

Performs the conversion.