Configure FIL address via ENV vars + show it in WebUI

[bajtos]

• At startup, get the FIL address to use from the env vars, e.g. FIL_ADDRESS.
• Modify the static HTML content served by /webui to show the address.
• Abort with a descriptive error when no address was provided.

[joaosa]

Context

As discussed with @bajtos and @patrickwoodhead on Slack, given Saturn L2 is currently loading the webui as an external dependency, sharing the FIL address config value (and any other future config values) will require us to have a standardized way to do so.

Decision

Having saturn-l2 expose an HTTP API seems like the sensible thing to do. There are, however, a few options in terms of API architecture that should be considered.

After checking the IPFS webui sister project, it can be seen it's using ipfs-http-client, which is its own HTTP RPC API client library (correct me if I'm wrong).
Following the same approach has the synergies of code reuse. However, this lib appears to be coupled to the IPFS use-case. Thus, making its usage less ideal and probably not the best fit.

To make an informed decision, we should consider any foreseeable future data flows. For instance, will we only ever expose/fetch discrete values or will we need want to vizualize more complex data? Is streaming an use-case?

Given this, here's a comparison of different approaches to expose an HTTP API to communicate with a browser frontend. I should note the general ideas behind this comparison came from here.

REST

The traditional solution which allows for a lot of flexibility in terms of implementation. It thrives in scenarios where API clients are unknown or where requirements are loose.

Flexibility is useful on the short-term but it builds entropy over time.

Given we control both ends of the contract (API client and server), a tighter integration could be beneficial in terms of enforcing expectations on both ends.

GraphQL

A declarative approach to empower clients to fetch their desired data fields without having the server-side implementation growing in terms of endpoint implementation complexity (as is the case with REST). It shines in product development use cases.

There are a couple of scenarios in which this could be useful:

• Having multiple distinct data sources for a single client which need to be rendered in a single view
  • GraphQL can hide the integration details and provide a single concise view
• Having multiple clients with different data field requirements for the same data source
  • GraphQL allows each client to independently query whatever fields they might require

Additionally, it allows fetching complex relational data models in a single request. However, we don’t have a relational data model and from my current understanding, it doesn't seem one would make sense.
Also, we're dealing with a 1-1 client to server mapping.

gRPC

It combines Google's lessons and knowledge in efficient remote communication for building complex distributed systems. It uses protobufs out of the box, which are a wire-efficient serialization protocol that enforces a data contract on both ends.
It uses code generation and features are dependent on the language implementation. It's a solid microservice solution.

It supports HTTP/2 transparently out of the box. It also has a bunch of more distributed system-oriented features (namely retries and deadline enforcement). It supports streaming use cases.

To run on a web browser, it requires https://github.com/grpc/grpc-web. This uses a modified protocol which doesn't use HTTP/2, but HTTP/1.1. This protocol change requires a conversion layer between regular grpc and grpc-web, which is probably overkill with our current use case.

json-rpc

A lightweight and simple RPC protocol meant to perform RPC calls using JSON. It is protocol agnostic meaning it can run over HTTP or WebSockets.

Library support exists, but it doesn't seem to be widely used. However, it is used by Ethereum clients.

This could be a way to have an RPC-like solution without the overhead associated with gRPC.

Consequences

Depending on the chosen solution, future use-cases might be more convoluted to implement.
Also, implementing a wholly new solution based on a tech which isn't used in other PL projects might add further external dependency complexity and skip the opportunity to reuse existing libraries and associated good practices. On the other hand, if the chosen solution is simple enough given the target use-case, it could be reasonable to do so.

[bajtos]

Great write-up, @joaosa 💪🏻

Since we don't need RPC semantics and our data model is not relational, it seems to me that we should KISS and implement the API as REST. What are your thoughts?

[joaosa]

Great write-up, @joaosa 💪🏻

Since we don't need RPC semantics and our data model is not relational, it seems to me that we should KISS and implement the API as REST. What are your thoughts?

Thank you @bajtos :)

Let's go for it. I agree it's the simplest solution given the current expectations.

[joaosa]

I suppose this can be closed 👍 (provided we're not including the integration with the https://github.com/filecoin-project/saturn-webui here)

[bajtos]

provided we're not including the integration with the https://github.com/filecoin-project/saturn-webui here

Done in #34