proposal: lexicons: modernize knot xrpc methods related to git #422

With the upcoming introduction of KnotMirror (git repo mirrors against entire network), we technically don't need most xrpc methods to interact with git repos, but third-party services might still want to depend on them. For example, users might make Knot-local web interface or third-party AppView without syncing from network.

Standardizing the hydrated ViewModel doesn't make much sense as they will change quite often. While KnotMirror reduces the "Knot api outdated" problem, we still want some kind of API to interact with knot and want to share same schema between internal and public APIs.

So instead of defining View methods from Knot, we can define Domain methods more closer to fundamental git objects (hope this explanation makes sense.) Instead of sh.tangled.repo.{branch,tag,tree} returning hydrated objects to render the repository, we can generalize them and make xrpc methods that can directly interact with core git concepts like trees and branches.

The implementation might not change much. The goal here is to make xrpc methods more git-friendly and closer to the internal domain than appview-specific concepts (ViewModel). Yeah, this proposal is more for organization purpose.

current knot xrpc methods related to the repository#

1. (procedure) repo.deleteBranch
2. (procedure) repo.forkStatus
3. (procedure) repo.forkSync
4. (procedure) repo.hiddenRef
5. (procedure) repo.mergeCheck
6. (procedure) repo.merge
7. (procedure) repo.setDefaultBranch
8. (query) repo.archive
9. (query) `repo.blob
10. (query) repo.branch
11. (query) repo.branches
12. (query) repo.compare
13. (query) repo.diff
14. (query) repo.getDefaultBranch
15. (query) repo.languages
16. (query) repo.log
17. (query) repo.tag
18. (query) repo.tags
19. (query) repo.tree

Few problems: repo.forkStatus and repo.mergeCheck are more closer to query than procedure, repo.branch naming is misleading as it basically returns a resolved commit, "default branch" is already well-known as different term in git; "HEAD", most methods are not following lexicon naming conventions.

new git xrpc methods#

updated methods:

1. (procedure) git.deleteBranch
2. (query) git.getForkStatus
3. (procedure) git.pullUpstream
4. (procedure) git.createHiddenRef
5. (query) git.analyzeMerge
6. (procedure) git.applyPatch
7. (procedure) git.putHead
8. (query) git.getArchive
9. (query) git.getEntity(repo, ref, path) and git.getBlob(repo, oid)
10. (query) git.getCommit
11. (query) git.listBranches
12. (query) git.getDiff(repo, base, head)
13. (query) git.getDiff(repo, head)
14. (query) git.getHead
15. (query) git.listLanguages
16. (query) git.listCommits
17. (query) git.getTag
18. (query) git.listTags
19. (query) git.getTree(repo, ref, path)

and some new methods: 20. (query) git.getObject(repo, oid, type?) 21. (query) git.listRefs(repo, prefix?) 22. (query) git.resolveRef(repo, ref) 23. (subscription) git.subscribeRefs(repo) (to replace /events endpoint)

summary:

• move under sh.tangled.git.* to be used as generic git xrpc interface. For example, all query methods can be supported from KnotMirror too.
• follow lexicon naming conventions
• merge some duplicated methods like repo.compare and repo.diff by making base optional.
• provide generalized methods like git.listRefs and git.getObject. For example, git.listBranches is equivalent to git.listRefs(prefix="refs/heads/"). We can share same schema between lexicons.
• git.getBlob will always serve the raw content. use git.getEntity to get structured metadata (this method won't return the content)