feat: introduced golem-network plugin api

[grisha87]

This PR introduces the plugin API I always wanted to introduce to the project.

The main motivators are described in the feature's documentation (see below).

Documentation

The feature documentation has been specified in the MD file:
https://github.com/golemfactory/golem-js/blob/feature/golem-plugins/docs/PLUGINS.md

Next steps

The implementation of plugin API enables code reuse and modularization, but doesn't influence how Golem Network behaves. This is an aspect that I want to leave to hooks which are another concept that I would like to implement next, that will be then a power combo with the plugin API introduced in this PR.

Example

A large example of how this works is attached here:

import { GolemNetwork, GolemPluginInitializer } from "../src";

const avgOf = (arr: number[]) => arr.reduce((a, b) => a + b, 0) / arr.length;

const checkGlmPriceBeforeStarting: GolemPluginInitializer<{
  maxPrice: number;
}> = async (_glm, opts) => {
  const response = await fetch("https://api.coinpaprika.com/v1/tickers/glm-golem");

  if (!response.ok) {
    throw new Error("Failed to fetch GLM price");
  } else {
    const data = await response.json();
    console.log("=== GLM Price ===");
    const price = parseFloat(data.quotes.USD.price);
    console.log("GLM price is", price);
    console.log("=== GLM Price ===");

    if (price > opts.maxPrice) {
      throw new Error("GLM price is too high, won't compute today :O");
    }
  }
};

const providerTracker: GolemPluginInitializer = (glm) => {
  const seenProviders: { id: string; name: string }[] = [];

  glm.market.events.on("offerProposalReceived", (event) => {
    const { id, name } = event.offerProposal.provider;

    const providerInfo = { id, name };

    if (!seenProviders.includes(providerInfo)) {
      seenProviders.push(providerInfo);
      console.log("Saw new provider %s named %s", id, name);
    }
  });

  return () => {
    console.log("Provider tracker found a total of %d providers", seenProviders.length);
  };
};

const offerTrackerPlugin: GolemPluginInitializer = (glm) => {
  const startPrices: number[] = [];
  const cpuPrices: number[] = [];
  const envPrices: number[] = [];

  glm.market.events.on("offerProposalReceived", (event) => {
    const { start, envSec, cpuSec } = event.offerProposal.pricing;
    startPrices.push(start);
    cpuPrices.push(cpuSec);
    envPrices.push(envSec);
  });

  console.log("Initialized offer tracker");

  const printStats = () => {
    const avgStart = avgOf(startPrices);
    const avgCpu = avgOf(cpuPrices) * 3600;
    const avgEnv = avgOf(envPrices) * 3600;

    console.log(
      "[OT Stats] Prices: AVG start %f, AVG CPU/h %f, AVG ENV/h %f (based on %d offers)",
      avgStart.toFixed(2),
      avgCpu.toFixed(2),
      avgEnv.toFixed(2),
      startPrices.length,
    );
  };

  const int = setInterval(printStats, 10_000);

  return () => {
    clearInterval(int);
    printStats();
    console.log("Offer tracker finished");
  };
};

(async () => {
  const glm = new GolemNetwork();

  // Example of a plugin with options
  glm.use(offerTrackerPlugin);

  // Example of a plugin without options
  glm.use(providerTracker);

  // Example of an async plugin
  glm.use(checkGlmPriceBeforeStarting, {
    maxPrice: 0.5,
  });

  // If the plugin requires options, not providing them will raise a TS error
  //glm.use(checkGlmPriceBeforeStarting);

  try {
    console.log("Connecting to Golem Network");
    await glm.connect();

    console.log("Acquiring resources from the market");
    const rental = await glm.oneOf({
      order: {
        demand: {
          workload: {
            imageTag: "golem/node:latest",
            minStorageGib: 1,
            // runtime: {
            //   version: "0.5.2",
            // },
          },
        },
        market: {
          rentHours: 15 / 60,
          pricing: {
            avgGlmPerHour: 1,
            model: "burn-rate",
          },
        },
      },
    });

    console.log("Deployng workload to the rental");
    const exe = await rental.getExeUnit();

    console.log("Running command on the workload");
    const result = await exe.run("df -h");
    console.log(result.stdout?.toString());

    console.log("Finalizing the rental and releasing resources to the market");
    await rental.stopAndFinalize();
  } finally {
    await glm.disconnect();
  }
})().catch(console.error);

[mgordel]

Good job, it looks very clean and readable. I played around with it a bit and it works fine.

There is one scenario where the user can cause the application to hang:
if he calls _glm.disconnect() from a plugin, the cleanup functions will not be executed. I know that we can't protect users from bad and stupid implementations ;)

It might be a good idea to include these examples from the PLUGINS.md in @examples/plugins - it would also be a test for CI

[grisha87]

Good job, it looks very clean and readable. I played around with it a bit and it works fine.

There is one scenario where the user can cause the application to hang: if he calls _glm.disconnect() from a plugin, the cleanup functions will not be executed. I know that we can't protect users from bad and stupid implementations ;)

It might be a good idea to include these examples from the PLUGINS.md in @examples/plugins - it would also be a test for CI

I was thinking about this, but resigned from the idea to not have our CI poke on the coinpaprika's API during builds to not make these examples tests even more fragile. But you're right, we can add more examples that won't need that API call. Will consider this for the next PR.