Mali: Minimalistic gRPC Framework

Common errors

• TypeError: Mali.addService is not a function

  cause Using `Mali.addService` in TypeScript with an older version that had incorrect type declarations, leading to compiler issues or runtime misinterpretations.
  fix Upgrade `mali` to `v0.44.3` or newer. Ensure correct method signature according to documentation if not using TypeScript.

• Error: Cannot find module '@grpc/grpc-js' or '@grpc/proto-loader'

  cause Mali lists `@grpc/grpc-js` and `@grpc/proto-loader` as peer dependencies, meaning they must be installed explicitly alongside `mali`.
  fix Run `npm install mali @grpc/grpc-js @grpc/proto-loader` to ensure all necessary peer dependencies are installed.

• Error: 14 UNAVAILABLE: No connection established

  cause The gRPC client failed to connect to the server. This could be due to the server not running, incorrect address/port, firewall issues, or network problems.
  fix Verify the server is running on the specified port and address. Check firewall rules. Ensure the client connection string matches the server's listening address.

Warnings

• breaking Mali `v0.47.0` officially dropped support for Node.js 14. Applications running on Node.js 14 might encounter issues or become unsupported.
  Fix: Upgrade Node.js to version 16 or newer. The project recommends Node.js 18+ for best compatibility and features.
• breaking In `v0.44.0`, several internal dependencies (`grpc-create-metadata`, `lodash.concat`, `lodash.forown`, `lodash.isplainobject`, `ascallback`) were removed. While primarily an internal cleanup for performance, if your project indirectly relied on these being available via Mali's dependency tree, it could cause runtime errors.
  Fix: Ensure direct dependencies are explicitly installed if your project relied on them. Review your package's dependency tree for unexpected removals.
• gotcha Older versions of Mali (`<0.44.3`) had an invalid TypeScript declaration for `Mali.addService`. This could lead to compilation errors or incorrect type inference when using `addService` in TypeScript projects.
  Fix: Upgrade to `v0.44.3` or newer to get the corrected TypeScript declarations.
• gotcha Versions prior to `v0.44.2` contained a bug that caused namespaces with the key `type` to be omitted from the gRPC service definition. This could lead to missing services or methods if your proto schema used `type` as a namespace key.
  Fix: Upgrade to `v0.44.2` or newer to resolve the namespace omission bug. Review your `.proto` files if they use `type` as a namespace key and test thoroughly.
• gotcha When sending response metadata, it was not always sent if an error occurred in versions prior to `v0.47.1`. This could cause clients to not receive expected metadata alongside error responses.
  Fix: Upgrade to `v0.47.1` or newer to ensure response metadata is always sent, even when an error occurs during processing.

Install

• npm install mali npm
• yarn add mali yarn
• pnpm add mali pnpm

Imports

• Mali
  wrong:

  const Mali = require('mali');

  correct:

  import { Mali } from 'mali';

  CommonJS `require` is typical for older Node.js projects, but ESM `import` is recommended for modern TypeScript/ESM projects.
• Context

  import type { Context } from 'mali';

  Importing the `Context` type for type-safe middleware definitions in TypeScript.
• App

  import { App } from 'mali';

  The main application class can also be imported as `App` for clarity in some contexts, though `Mali` is the primary export.

Quickstart

This quickstart demonstrates setting up a basic Mali gRPC server, defining a simple 'Greeter' service with a 'SayHello' method, and then creating a client to interact with it. It includes the necessary proto definition and server startup/shutdown.

const Mali = require('mali');
const path = require('path');
const fs = require('fs');

// A minimalistic gRPC service definition
const PROTO_CONTENT = `
  syntax = "proto3";

  package helloworld;

  service Greeter {
    rpc SayHello (HelloRequest) returns (HelloReply) {}
  }

  message HelloRequest {
    string name = 1;
  }

  message HelloReply {
    string message = 1;
  }
`;

// Write the proto content to a temporary file for Mali to load
const PROTO_PATH = path.resolve(__dirname, 'helloworld.proto');
fs.writeFileSync(PROTO_PATH, PROTO_CONTENT);

function sayHello (ctx) {
  ctx.res = { message: `Hello ${ctx.req.name || 'World'}` };
  console.log(`Handled SayHello for ${ctx.req.name || 'World'}`);
}

async function main () {
  const app = new Mali(PROTO_PATH);
  app.use({ sayHello });
  const port = '0.0.0.0:50051';
  app.start(port);
  console.log(`gRPC server running on ${port}`);

  // Basic client to test the server (optional, for demonstration)
  const grpc = require('@grpc/grpc-js');
  const protoLoader = require('@grpc/proto-loader');
  const packageDefinition = protoLoader.loadSync(PROTO_PATH, { keepCase: true, longs: String, enums: String, defaults: true, oneofs: true });
  const hello_proto = grpc.loadPackageDefinition(packageDefinition).helloworld;
  const client = new hello_proto.Greeter(port, grpc.credentials.createInsecure());

  client.sayHello({ name: 'Mali User' }, (err, response) => {
    if (err) {
      console.error('Client error:', err);
    } else {
      console.log('Client received:', response.message);
    }
    // Clean up temporary proto file and stop the server for a real test
    fs.unlinkSync(PROTO_PATH);
    app.shutdown();
  });
}

main().catch(console.error);