Amend File API design document to address file.Close constraints

[oleiade]

What?

This Pull Request updates the File API design document, focusing on the limitations of the file.Close operation, especially when files are opened in the init context.

Why?

The current design treats the file.Close operation as a non-operation, as detailed in #3314. This choice was by design, as we anticipated changing this once k6 can open files during the VU stage.

We've explored an alternative where k6 tracks how many times a file has been opened. When this count reaches zero, k6 would free up the memory holding the file content. More details can be found in the proof-of-concept for this approach.

A challenge arose: opening files in the init context means the count might never reach zero. This is because the file keeps a reference until the test concludes.

After discussions with @codebien, we agreed that due to k6's lifecycle stages and the init context's frequent calls, the best approach would be to:

• Adopt the reference count approach.
• Keeping data in memory as long as the init context code hasn't closed the file to a point where zero references are left.
• Close the file and free memory only at the test's end, possibly using the newly added event system.

When #3020 is in place, our plan is to adjust this so that files opened exclusively in the VU stage can have their memory released earlier, given they are consistently closed in that stage.

Refs

#3149
#3101
#3314
#3020

[codecov-commenter]

Codecov Report

Attention: 108 lines in your changes are missing coverage. Please review.

Comparison is base (c944ebf) 73.16% compared to head (f1ebad0) 73.33%.
Report is 65 commits behind head on master.

❗ Current head f1ebad0 differs from pull request most recent head 4528f56. Consider uploading reports for the commit 4528f56 to get more accurate results

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #3328      +/-   ##
==========================================
+ Coverage   73.16%   73.33%   +0.16%     
==========================================
  Files         258      258              
  Lines       19912    19645     -267     
==========================================
- Hits        14569    14407     -162     
+ Misses       4418     4353      -65     
+ Partials      925      885      -40     

Flag	Coverage Δ
ubuntu	73.27% <50.68%> (+0.18%)	⬆️
windows	73.18% <50.68%> (+0.16%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files	Coverage Δ
cmd/root.go	94.26% <100.00%> (ø)
js/bundle.go	85.90% <100.00%> (ø)
js/console.go	94.28% <100.00%> (+0.16%)	⬆️
js/modules/k6/http/request.go	84.27% <100.00%> (+0.09%)	⬆️
js/summary.go	89.87% <100.00%> (ø)
lib/consts/consts.go	51.61% <ø> (ø)
lib/netext/grpcext/conn.go	88.88% <100.00%> (+3.17%)	⬆️
lib/netext/httpext/batch.go	100.00% <ø> (ø)
output/cloud/expv2/hdr.go	100.00% <100.00%> (ø)
output/csv/config.go	74.50% <ø> (-2.69%)	⬇️
... and 9 more

... and 4 files with indirect coverage changes

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[codebien]

@oleiade We should move this change to the possible future improvements section and update it by integrating #3149 (comment).

[oleiade]

Agreed 👍🏻

What did you refer to as the possible future improvements section?

[codebien]

https://github.com/grafana/k6/blob/master/docs/design/019-file-api.md#possible-future-improvements

[oleiade]

@codebien I see, you meant the one in the file directly 🙇🏻 Fair enough, I'll amend the document 👍🏻

[oleiade]

✅