Update FilePath constructors to allow a non-partial way to create a FilePath

[rhagenson]

Closes #3820

As part of RFC 70, FilePath now has two constructors: create and from. Where previously create was a partial constructor and thus could fail if called with a FilePath base, now create is a complete constructor and will always succeed. Partial construction with FilePath now exists in the from constructor.

A new package-level root authority, FileAuth, has been added to allow explicit "files" authority without AmbientAuth. This new authority follows the same convention as is used in the "net" package -- note: this change is different from the the accepted RFC in order to maintain consistency within stdlib 's use of package-level root authority. Any prior instance where AmbientAuth was accepted in relation to FilePath now also accepts FileAuth with the same result.

Additional tests have been added to cover the expected error behavior of FileAuth.from(...), as well as the creation and use of FileAuth in place of AmbientAuth.

[Theodus]

Closes #3820

[SeanTAllen]

I'm loiking forward to this one.

[rhagenson]

@SeanTAllen This is (I believe) my first contribution to the stdlib so I am looking forward to it as well.

I have all the tests passing now. I still need to add the additional test(s) for the change and want to look at stdlib/tests to see if I can reduce the size of try-blocks now that create cannot error. The former is guaranteed, the latter is "with this change can we have cleaner code in stdlib" thinking.

Also kind of surprised the following in mkdtemp works:

...
    let parent: FilePath = match base
      | let base': FileAuth => FilePath(base', dir)
      | let base': FilePath => FilePath.from(base', dir)?
    end
...

I would expect parent: (FilePath | None) with FilePath.from(base', dir)? being partial. Or, alternatively FilePath.from(base', dir)? to require a try-block.

[SeanTAllen]

mkdtemp is defined as partial. I assume that hasn't changed...

  new val mkdtemp(
    base: (FilePath | AmbientAuth),
    prefix: String = "",
    caps': FileCaps val = recover val FileCaps .> all() end)
    ?

and it would explain the working without a try.

[rhagenson]

Ah, I was not thinking big enough. I had assumed the part I rewrote to now only sometimes failing would have bubbled up more, but at the function level it is already denoted as possibly failing.

[rhagenson]

I finished the split of FilePath construction to be create with new FileAuth and from with FilePath, fixed existing code in stdlib for this change, added tests for successful and failing serial construction. Last thing I know I need to write for this is a changelog entry, but I am going to open it up for review prior to sync tomorrow.

[SeanTAllen]

@rhagenson before this gets merged, can you update the first comment on this PR to be a good summation of the changes that this encompasses and link to the rfc? We'll use that as the squashed commit comment and if anyone follows the link from the CHANGELOG to this PR, they will find a good summary at the top.

Please include Closes #3820 as part of that reworked comment.

[SeanTAllen]

@rhagenson let me know if you would like any assistance with this.

[rhagenson]

I will make a point to get all the suggested changes in place today. I have been wrapped up in other matters so have not gotten back to this. I recognize that y'all are waiting on me so moving it up in priority. I do not think I will need assistance.

[SeanTAllen]

@rhagenson no rush. was checking, nothing more.

[rhagenson]

@SeanTAllen Top comment rewritten and all direct mentions of AmbientAuth back to using AmbientAuth (i.e., revert my FileAuth(ambient) wrappings).

Please let me know if there is anything else that is needed.

[ergl]

Looks good! I have left some comments below about the documentation blocks

[SeanTAllen]

I think this change with let auth temporary variable should be reverted. it hides the "actual change".

[rhagenson]

Good catch!

[SeanTAllen]

This looks good to me. I added one small change request and otherwise, I do agree with @ergl's couple of notes. Looking pretty good though.

[rhagenson]

@ergl and @SeanTAllen I took at your comments into account. While fixing the removal of let auth = env.root as AmbientAuth in Sean's comment I did another search for instances of my previously necessary FileAuth(auth) wrapping and removed more of them -- namely in process/_test.pony.