i published a rust crate!

Published on 2024-12-17 • Updated on 2024-12-17

i needed a file locking implementation for another project i'm working on, and none of the ones i found on crates.io seemed to satisfy everything i wanted:

simple api (basically just "try to get an exclusive lock on a whole file"): many crates provide features like async compatibility, locking byte ranges, etc. that i just didn't need
non-blocking: a few crates were based on stuff like O_EXCL on POSIX or specifying a restrictive share mode on Windows, which has the problem that the only way to try to get the lock is to commit to a potentially blocking operation
guaranteed cleanup on crash: this is another problem with using exclusive open modes as a locking mechanism (the file can be left behind on a crash, leaving no way to know if the lock is held or not)
portable: a few crates only work on one platform family, typically POSIX
uses standard bindings to the native locking api instead of rolling custom ones
based on flock() on POSIX systems, not fcntl(): conventional wisdom actually says to prefer fcntl() locks because they're more stable across network shares, but for the use case i'm interested in (only allowing 1 process access to a particular directory), flock() is better-behaved because it applies to a single file descriptor rather than every file descriptor in the process

so, i made this crate! it's about as simple as i could make it while fulfilling everything i wanted.

i've never released a rust crate (or really any publically-available package) before, so it was a bit of an interesting experience. here's the highlights:

i found one neat tool that helped with the process a little bit, cargo msrv, which helps you find the minimum supported rust version for your crate
i was surprised that you need a github account to publish a crate, despite the fact that you don't need to host your crate's source on github; they seem to use it just as an authentication provider. which i honestly don't really have a problem with, but it's a little odd
there's a handy checklist of all the things you need to check before you publish a crate, which i found very helpful; i wouldn't have remembered to add crate-level documentation or to write my code examples with ? instead of unwrap(), for example
i got around 150 downloads in the first couple days that the crate's been up, but i'm preeeeetty sure that those are mostly indexing/mirroring/etc. bots that just happen to download the crate to do their job, not to actually use it. so i have no idea how many real users i have 🙃

i hope at least a few other folks find it useful! c: