Missing Feature Implied by Documentation: file mode
Nobody has claimed this yet.
Assessment
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Newbie friendliness
- 45/100
Research direction
The behaviour lives in lib/tempfile.rb: the Tempfile.create path ORs the internal open flags with the caller's mode argument, and the documentation block near lines 571-575 claims permissions are 0600 with a reference to File Permissions. Read that code and the matching docs, then decide whether to make the permission bits configurable or to document and warn about the flag handling. Done means the doc and behaviour agree, and the chosen approach is covered by tests in test/ for Tempfile.create.
Written by the indexing model from the issue text.
Description
Context
I'm using Tempfile.create to update an existing file. I'm creating a Tempfile in my target directory, and inside the block of the ::create invocation, I'm writing to the file, closing it, and -- if everything checks out -- I'm using FileUtils.mv to move it into place atomically (potentially overwriting the existing file).
How I Encountered This
I was just trying to troubleshoot an issue where, despite me adding mode: 0o644 to Tempfile.create, I was creating a file (even before the move) with mode 0600. I quickly realized my mistake: the keyword argument mode, of course, refers to the open mode/flags given to File.open, rather than the argument ruby calls perms.
The Issues
While I fully admit that reading every line of the documentation and what it links to would have mostly cleared this up, this isn't what developers typically do (or should be assumed to do) and the documentation arguably encouraged my particular misunderstanding.
On top of that, even read completely, the documentation suggests a feature that doesn't exist and -- ideally -- should (barring that, it's absence should be documented):
The issues are twofold:
-
Tempfile.createdoesn't issue so much as a warning when open flags are explicitly given that aren't suitable for use with the creation of a temporary file.Instead, the flags needed by
Tempfileare logically 'OR'ed with the ones passed (see code above), potentially causing other hard-to-trace errors in how the file gets created.For example, on Linux,
File::RDWRis2, butFile::WRONLYis1. These two flags are not normally meant to be used together, and have a special/specific meaning on Linux.Per
man 2 open:Linux reserves the special, nonstandard access mode 3 (binary 11) in flags to mean: check for read and write permission on the file and return a file descriptor that can't be used for reading or writing. This nonstandard access mode is used by some Linux drivers to return a file descriptor that is to be used only for device-specific
ioctl(2)operations.Lastly, though less likely (and inadvisable for security reasons), a value that intends to set the
setuidand/orsetgidflags in a file's mode would result in the it being inadvertently opened in append or non-block mode. -
Potentially worse, the docs suggests the newly-created files' permissions are configurable.
The issue here is that under
With no block given and no arguments, creates and returns file whose:, the bulleted list that follows includesPermissions are 0600; see File Permissions.It is reasonable to assume from this that the permissions of the temporary file are configurable, when they are, in fact, hardcoded.
In my case -- and I would have to imagine others have reached, and are liable to reach, the same conclusion -- the only argument listed that could plausibly control this seemed to be
mode, so I assumed I didn't need to look any further.
Suggested Fix
Catching when the developer confuses open flags with the new file's mode is kind of tricky. Particularly because any red-flag values would be OS dependant and -- it could be argued -- don't even belong in this library. I'm also a little bit surprised the Linux doesn't seem to refuse to open a file if unrecognized open flags are given, but this might not be the case on other OSes or even other libc implementations.
In any case, I think this -- as well as the documentation confusion -- can both be easily addressed by just making the new file's permissions mode configurable, and documenting the argument that controls it. Like what is currently done for the open flags, any bits that need to be set for Tempfile to work can be logically ORed with the provided value. For example, at the very least, the user write bit.
On the other hand, whether the user read bit should be enabled depends, I think, on what it was intended the ORing of the open flags would do if File::WR_ONLY was passed explicitly. As mentioned, it probably depends on the OS and/or libc implementation which takes precedence. In any case, I would only automatically add the user read bit to the file's mode if the file isn't to be opened in read-write mode. If opening for writing isn't mandatory, and neither the open flags or file mode are specified, it may make sense to defer to if reading is blocked by the umask.
Lastly, I would at least document that -- even if the open mode is specified -- certain bits will be forced to on in the provided value. Honestly, I'm not sure if changing a non-default value is the best practice in the first place and think it makes more sense to let a relevant error be thrown, but that would obviously a breaking change. I think ideally, at least a warning should be omitted if the tempfile library alters these values.
Please let me know if I can be of any help in making this change. It's very likely I can do the PR if you can tell me this change would be approved.
Thanks!
- Dominant language
- Ruby
- Stars
- 35
- Forks
- 11
- Avg merge
- 1h 57m
- Merged PRs (30d)
- 3
Getting set up
This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from ruby/tempfile
-
Difficulty 2/5 1-3 hours Newbie friendliness 45/100
-
JRuby supportOpen
Difficulty 5/5 Over a week Newbie friendliness 25/100
Similar issues
-
🐛 bug 👩💻 équipe CE 🧑🏭 entreprises
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
betagouv/conseillers-entreprises#4808 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
yosiat/panko_serializer#250 ·
-
Difficulty 1/5 Under an hour Newbie friendliness 75/100
cline/mcp-marketplace#3886 ·
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100