Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Documentation for NetworkPlugin #4579

Open
seibelj opened this issue Feb 5, 2024 · 2 comments
Open

Add Documentation for NetworkPlugin #4579

seibelj opened this issue Feb 5, 2024 · 2 comments
Labels
documentation Documentation related issue. on-deck This Enhancement or Bug is currently being worked on. v6 Issues regarding v6

Comments

@seibelj
Copy link

seibelj commented Feb 5, 2024

Suggestion

I need to add the ability for a custom HTTP header to every request to the provider, as our node provider requires a Bearer auth token. I believe the way to do this is with NetworkPlugins, and I'm trying to read the source code to understand if it can be used to intercept HTTP calls to add a header, but it's confusing.

I would add:

  • The purpose of NetworkPlugins
  • What they can do
  • An example on how to implement one
@seibelj seibelj added the documentation Documentation related issue. label Feb 5, 2024
@seibelj
Copy link
Author

seibelj commented Feb 5, 2024

I figured out that you can just pass a new FetchRequest to the JsonRpcProvider constructor:

const fetcher = new FetchRequest(rpcUrl);
fetcher.setHeader(
    "Authorization",
    `Bearer ${api_key}`
);

NetworkPlugin would still be useful to document, it seems powerful.

@ricmoo
Copy link
Member

ricmoo commented Feb 6, 2024

The NetworkPlugin is more for internal uses, to allow changes that might otherwise be major breaking changes, but to keep the internal change local.

Once a NetworkPlugin is exposed, then it becomes part of the public API, like the FeeDataNetworkPlugin which was added to allow networks to override fee data, which Polygon uses to access gas stations instead of the normal EIP-1559 sources (which don't produce valid results for Polygon). If a public API is required to be added, then I can easily add a public-facing NetworkPlugin though, so if there is a need, just let me know. :)

For the most part, sub-classing Provider should suffice for your use case though. For example, in your case, I'd prolly use:

class MyProvider extends JsonRpcProvider {
  constructor(url: string | UrlRequest, network?: Network, options?: JsonRpcProviderOptions) {
    if (typeof(url) === "string") { url = new FetchRequest(url); }
    url = url.clone();
    url.setHeader("Authorization", `Bearer ${ API_KEY }`);
    super(url, network, options);
  }
}

There are other features available on the FetchRequest object though for more advanced authentication. For example, often with a Bearer, you may need to sign the request. You can use the above pattern to wrap this behaviour as well, but if curious:

const request = new FetchRequest(someUrl);
request.preflightFunc = (req: FetchRequest) => {
  // The req here is a clone; you may modify freely without affecting the JsonRpcProvider
  const signature = mySigningFunc(req.url, req.body, (new Date()).getTime());
  req.setHeader("Authorization", `Bearer ${ myApiKey }:${ signature }`);
};

This will sign every request via the Bearer, with the url, body and current time. It is called before each request, including retries due to 429 requests, redirects, etc. This provides the most flexibility in making requests.

I have a backlog of documentation points I need to add, so I'll try to add this example to the Cookbook. I'm bringing on a second person to the team soon, so should have more time and help to flesh out the docs. :)

@ricmoo ricmoo added on-deck This Enhancement or Bug is currently being worked on. v6 Issues regarding v6 labels Feb 6, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Documentation related issue. on-deck This Enhancement or Bug is currently being worked on. v6 Issues regarding v6
Projects
None yet
Development

No branches or pull requests

2 participants