surf: convert to git-ref-format

[FintanH]

radicle-surf, historically, defined its own domain of reference types. This has, historically, caused some headaches for converting from surf types into radicle-link types. Now that git-ref-format is available to surf, we should plan out the conversion of the API to use those types instead.

• Look at the current API and where it uses reference types
• Plan out a migration path based on the above

Some things to consider:

• Whether the input should always be Qualified, ie. have a category like refs/heads, refs/tags, refs/remotes
• If we should do any newtype'ing to distinguish qualified refs, e.g. pub struct Tag(Qualified), with smart constructors
• Are namespaces important anymore if we go down the protocol route of having a single repo per project? Thus, keep namespaces in the API but can de-prioritise the implementation of them

[cloudhead]

Good point about namespaces; we aren't using them in the new protocol!

[keepsimple1]

When I was working on the PR, I was wondering what are the best examples of git-ref-format's benefits? I understand the points in its doc page, but it is not clear to me how much benefits it brings to overweigh the cost.

[FintanH]

When I was working on the PR, I was wondering what are the best examples of git-ref-format's benefits? I understand the points in its doc page, but it is not clear to me how much benefits it brings to overweigh the cost.

What are the costs you refer to here?

The benefits are:

• It's a well-typed interface. It's useful to constrain your domain to well-known types, i.e. RefStr/RefString are valid references, Qualified is a valid reference that begins with refs/<category>, Namespaced is a valid reference that begins with refs/namespaces, and PatternString/PatternStr are valid refspecs. This is opposed to haphazardly passing around strings that we hope are correct. Another way of thinking about this is, "Parse, Don't Validate"
• We use git-ref-format in important places such as git-storage, radicle-cob, and radicle. That means that those libraries will already passing around and returning types from git-ref-format.

[keepsimple1]

Thanks. The costs I was referring to are fallible constructions of types in git-ref-format.

[FintanH]

Closed via #48