A hiproxy plugin example
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
screenshot
src
.gitignore
LICENSE
README.md
index.js
package.json

README.md

hiproxy-plugin-example

hiproxy插件示例。这个插件为hiproxy添加了一个Rewrite指令、一个CLI命令和一个页面路由。

  • 名令hello,执行hiproxy hello --name <your-name> --age <your-age>
  • 指令add,在rewrite文件中使用add $add_value 1600 88;
  • 路由test,服务启动之后,访问http://127.0.0.1:<port>/test

安装

npm install hiproxy/hiproxy-plugin-example -g

注意:必须要把插件安装到全局。hiproxy CLI默认去全局查找插件,所以必须保证安装到npm root -g所在的目录中,才能被正确加载。


使用

安装完成后,hiproxy会自动加载所有安装的插件并注册插件定义的命令、指令和页面。


命令

安装好这个示例插件之后,执行hiproxy --help,可以看到如下信息,从中我们能发现,有了hello这个命令。

command-hello

执行hp hello --help,可以看到hello命令的帮助信息。

hello-help


页面

hiproxy-plugin-example为hiproxy添加了一个页面,url为/test,使用hiproxy start --port 8888启动服务之后,可以访问http://127.0.0.1:8888/test查看效果。


指令

hiproxy-plugin-example为hiproxy添加了一个rewrite指令add来做加法运算。指令的作用域为[global, domain, location],这个指令接收三个参数:

  • key:属性名称,用于把计算后得到的值赋值给当前作用于的props,比如:$result
  • num1:第一个加数,比如:12
  • num2:第二个加数,比如:34

之后,我们可以使用这个计算出来的值,比如:set_header Calc-Result $result

示例:

# rewrite rules
# need plugin `hiproxy-plugin-example`

set $gvar global-value;

domain test.hiproxy.io {
  set $host test.hiproxy.io;

  # hiproxy-plugin-example提供的指令
  add $addresult 9999 90000;

  location / {
    proxy_pass http://127.0.0.1:8000/;

    # hiproxy-plugin-example提供的指令
    add $add_value 1600 88;

    # 使用`add`计算的结果
    set_header Add_Result $addresult;
    set_header Test_Add_Value $add_value;

    set_header Global_Var $gvar;    
  }
}

开发者

开发者开发新插件时,可以参考hiproxy-plugin-example


插件结构

插件作为一个独立的模块安装,入口文件需要导出一个对象,包括三个属性:

  • commands: <Array>,用来扩展hiproxy的CLI命令,数组中每个对象作为一个命令配置,具体配置见命令配置

  • directives: <Array>,用来扩展hiproxy的rewrite指令,数组中每个对象作为一个指令配置,具体配置见指令配置

  • routes: <Array>,用来扩展hiproxy的页面路由,数组中每个对象作为一个路由配置,具体配置见路由配置


命令配置

命令可以配置的内容为:命令名称描述使用方法处理函数命令选项参数。对应的字段为:

  • 命令名称(command):<String>,比如:'hello'
  • 描述信息(describe):<String>,简单介绍命令的作用以及其他的信息,比如:'A test command that say hello to you.'
  • 使用方法(usage):<String>,命令的使用方法提示信息,比如:'hello [--name <name>] [-xodD]'
  • 处理函数(fn):<Function>,执行命令时,调用的函数。函数调用时this值为命令行参数解析后的对象。
  • 命令选项(option):<Object>,命令对应的选项,key:value形式。可以参考https://github.com/hemsl/hemsl

一个完整的命令示例如下:

{
  command: 'hello',
  describe: 'A test command that say hello to you.',
  usage: 'hello [--name <name>] [-xodD]',
  fn: function () {
    var cliArgs = this;

    console.log('Hi, welcome to use hiproxy example plugin');
    if (cliArgs.name ) {
      console.log('your name is', cliArgs.name.green);
    }

    if (cliArgs.age ) {
      console.log('your are', cliArgs.age.green, 'years old');
    }
  },
  options: {
    'name <name>': {
      alias: 'n',
      describe: 'your name'
    },
    'age': {
      alias: 'a',
      describe: 'your age'
    }
  }
}

指令配置

命令可以配置的内容为:指令名称作用域处理函数。对应的字段为:

  • 指令名称(name):<String>,比如:'add'
  • 作用域(scope):<Array>,指令对应的作用域,只有在这里指定的作用域里面才会执行。可选择的作用域为:globaldomainlocationrequestresponse
  • 处理函数(fn):<Function>,执行指令时,调用的函数。

一个完整的指令示例如下:

{
  name: 'add',
  scope: ['global', 'domain', 'location'],
  fn: function (key, a, b) {
    var props = this.props;
    var value = Number(a) + Number(b);

    this.props[key] = value;
  }
}

路由配置

路由可以配置的内容为:路由规则渲染函数。对应的字段为:

  • 路由规则(name):<String>,比如:'add'
  • 渲染函数(render):<Function>,渲染页面,接收三个参数:(route, request, response)route为url匹配后的对象,细节可以查看https://www.npmjs.com/package/url-pattern

一个完整的指令示例如下:

{
  route: '/test(/:pageName)',
  render: function (route, request, response) {
    response.writeHead(200, {
      'Content-Type': 'text/html',
      'Powder-By': 'hiproxy-plugin-example'
    });

    var serverInfo = {
      route: route,
      pageID: route.pageName,
      time: new Date(),
      serverState: {
        http_port: global.hiproxyServer.httpPort,
        https_port: global.hiproxyServer.httpsPort,
        cliArgs: global.args,
        process_id: process.pid
      }
    };

    response.end('<pre>' + JSON.stringify(serverInfo, null, 4) + '</pre>');
  }
}