`goal` improvements: `algod` curl alias

tzaffi commented 1 year ago

Enable easier querying of `algod` endpoints directly in `goal`

Even though goal supports most of the algod endpoints there are certain situations in which a raw HTTP request to the endpoint is desirable. For example:

sometimes a new endpoint comes online that isn't yet supported in goal
need to get the raw response from algod without any opinionated presentation that goal imposes

Developers are likely to use a tool such as postman or unix curl in these cases (or any of the SDK's of course). However, there is some boilerplate that needs to be taken care of. For example, it's possible to write a script that looks like the following tying all the boilerplate together:

#! /usr/bin/env bash
set -euo pipefail
ALGORAND_TOKEN=$(cat $ALGORAND_DATA/algod.token)
ALGORAND_ALGOD=$(cat $ALGORAND_DATA/algod.net)
curl -X $1 "http://${ALGORAND_ALGOD}$2" -H "Authorization: Bearer ${ALGORAND_TOKEN}"

Solution

Introduce new goal GET and goal POST commands that can be called on any of our algod endpoints. For example, if the ALGORAND_DATA env var has been set appropriately we could have:

❯ goal POST /v2/ledger/sync/1337

❯ goal GET /v2/ledger/sync
{"round":1337}

❯ goal GET /v2/blocks/1337
{
  "block": {
    "earn": 27,
    "fees": "Y76M3MSY6DKBRHBL7C3NNDXGS5IIMQVQVUAB6MP4XEMMGVF2QWNPL226CA",
    "frac": 280027324,
    "gen": "mainnet-v1.0",
    "gh": "wGHE2Pwdvd7S12BL5FaOP20EGYesN73ktiC1qzkkit8=",
    "prev": "blk-4SI6SDKSEWJX2JV3O5UVR2J4H5JZQN6567WVPJITJTHC3YUVJTAA",
    "proto": "https://github.com/algorandfoundation/specs/tree/5615adc36bad610c7f165fa2967f4ecfa75125f0",
    "rate": 20000000,
    "rnd": 1337,
    "rwcalr": 500000,
    "rwd": "737777777777777777777777777777777777777777777777777UFEJ2CI",
    "seed": "PQVI8SyBSz2C2MNE8ERIP2S1UVaBUaIbpyH9T/9Ec/4=",
    "ts": 1560244625,
    "txn": "tGWqr06HVvsHC2hFmu2EhwYBSiMkvIoo5nWxAkUxsLo="
  }

Tasks

[ ] Design doc for UX
[ ] Consensus on design doc
[ ] Implementation

Implementation Considerations

An MVP for this wouldn't provide a comprehensive solution to querying all of our endpoints. However, it's worth considering the following questions when implementing:

To consolodate around algokit as a standard, keep in mind the likely usage via algokit goal and algokit goal console. In particular, this suggests de-prioritizing the problem of sessions since in the algokit context, the data directory is already managed for the user.
Should we support the DELETE verb?
Should we check that the route is sensible before attempting to query?
Should we handle multiple parameters?
Should we support various encodings such as base64 and ABI?
- for the inputs?
- for the output?
Should this just be a new command such as algocurl?
Instead of goal GET maybe this should be goal algod GET and be a subcommand of goal algod (cf. #5374)

Dependencies

Implementing sessions via #5376 would aid in the user experience

Urgency

Medium - devs seem to want this once they know of this option

bbroder-algo commented 1 year ago

Maybe create a utility to generate a curl -K config file for the algod?

tzaffi commented 1 year ago

Maybe create a utility to generate a curl -K config file for the algod?

This reminds me of goal completion so a bit more unwieldy than what I'm proposing. Also, I'm not a curl expert so am not sure how to make use of such a config or configs. But it does sound like it might provide a more lightweight yet comprehensive approach. Worth further exploration.

bbroder-algo commented 1 year ago

I think goal algod get / goal algod post sound like useful dev/devops tools

algochoi commented 1 year ago

I think this would be a nice UX improvement - I personally use curl more than goal to call endpoints directly. I think the biggest nuisance is passing in different parameters e.g. in the disassemble endpoint

bbroder-algo commented 1 year ago

Found myself wanting this again just now

algorand / go-algorand