# birdv3

> birdv3 is a proxy server with cas auth built in, originate from `bird`

Latest version **0.3.39** (published 2019-01-25) · MIT license · 0 weekly downloads

## Install

```sh
npm install birdv3
pnpm add birdv3
yarn add birdv3
bun add birdv3
```

## Health

**Score 15/100 (F)** — status: abandoned.

Positive: no vulnerabilities.

Warnings: low downloads; no types; no esm support; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.3.39 |
| Published | 2019-01-25 |
| First published | 2016-05-26 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | none |
| Module format | CommonJS |
| Dependencies | 19 |
| Unpacked size | 180.7 KB |
| Known vulnerabilities | 0 (+15 in 4 direct dependencies) |
| Install scripts | no |
| GitHub stars | 15 |
| Maintainers | befe-owner, moyuyc |

## Links

- npm: https://www.npmjs.com/package/birdv3
- Repository: https://github.com/chenchengxing/bird-v2
- Issues: https://github.com/chenchengxing/bird-v2/issues
- npm.io page: https://npm.io/package/birdv3

## Dependencies (19)

- [touch](https://npm.io/package/touch.md) ^1.0.0
- [colors](https://npm.io/package/colors.md) 1.1.2
- [delete](https://npm.io/package/delete.md) 0.3.*
- [lodash](https://npm.io/package/lodash.md) 4.11.*
- [weinre](https://npm.io/package/weinre.md) 2.0.0-pre-I0Z7U9OV
- [cheerio](https://npm.io/package/cheerio.md) 0.19.0
- [express](https://npm.io/package/express.md) 4.13.3
- [request](https://npm.io/package/request.md) 2.67.0
- [bluebird](https://npm.io/package/bluebird.md) 3.1.5
- [casperjs](https://npm.io/package/casperjs.md) 1.1.4
- [copy-dir](https://npm.io/package/copy-dir.md) 0.0.*
- [commander](https://npm.io/package/commander.md) ^2.9.0
- [phantomjs](https://npm.io/package/phantomjs.md) 2.1.7
- [http-debug](https://npm.io/package/http-debug.md) ^0.1.2
- [mime-types](https://npm.io/package/mime-types.md) 2.1.8
- [json-buffer](https://npm.io/package/json-buffer.md) ^3.0.0
- [shellpromise](https://npm.io/package/shellpromise.md) ^1.4.0
- [concat-stream](https://npm.io/package/concat-stream.md) ^1.6.0
- [shell-promise](https://npm.io/package/shell-promise.md) ^1.0.0

## Recent versions

- 0.3.39 (latest) — 2019-01-25
- 0.3.38 — 2019-01-24
- 0.3.37 — 2019-01-07
- 0.3.36 — 2019-01-07
- 0.3.35 — 2018-09-19
- 0.3.34 — 2018-08-30
- 0.3.33 — 2018-03-15
- 0.3.32 — 2017-10-19
- 0.3.31 — 2017-10-18
- 0.3.30 — 2017-09-28
- 0.3.29 — 2017-05-03
- 0.3.28 — 2017-05-03
- 0.3.27 — 2016-08-12
- 0.3.26 — 2016-08-11
- 0.3.26-rc1 — 2016-08-11
- … 54 more at https://npm.io/package/birdv3/versions

## README

# Bird 前后端分离开发工具

## 如何使用

### 安装 (作为开发依赖)

强烈推荐作为项目的一个开发依赖来使用, 这样, 你的bird配置已经整体的开发工具链, 都可以作为项目的一部分提交到代码中, 方便后续人员开发时使用

```
cd my-project-folder
npm install --save birdv3
```

推荐在你的项目中创建一个 `bird/` 文件夹, 里面的结构如下:

```
bird/
    |-- birdfile.js
    |-- bird-server.js
```

其中, birdfile.js 为你的bird配置文件, 它的格式可以参照下面的 bird config

bird-server.js 很简单, 为:

```
var bird = require('birdv3')
bird('./birdfile.js')
```

### 安装 (作为全局的工具)

当然, bird也还是作为全局的命令使用, 但不推荐

```
npm install -g birdv3
bird ./some/path/to/birdfile.js
```

### 作为中间件使用

bird也支持中间件使用, 与开发依赖安装类似, 你需要有一个 birdfile.js, 然后在你的server脚本中, 加入以下的代码:

**注意!! 最好把bird放置在所有其他的中间件或request handler后面**
 
```
var bird = require('birdv3')

...

// 假设 app 是一个 express 服务器对象
app.all('*', bird('./path/to/birdfile.js'))

...
```

### 上报数据到接口平台

bird还可以将从服务器取回的数据上报,然后接口平台可以帮你生成可视化的接口文档

- [配置样例](./config_example/11-config-platform/birdfile.js#L23-25)
- 如果projectId在配置中不存在,那么你将要在首次启动bird的时候配置一次
- 如果需要修改projectId,请优先在config中修改

## Bird config file 配置

参照带 [注释的 Bird Config file](./config_example/birdfile_example.js)

## CHANGE LOG

### v0.3.24
- 增加上报接口平台功能
- 增加配置projectId功能
- 增加上报时候gzip content-encoding的处理
- 增加上报时候的错误捕获而不影响其他流程

## 开发指南

### 代码组织

- 本项目是一个 matriks 项目
- 主要的bird核心在 `project/locals/lib/` 下面
- 入口文件为 `index.js` => `project/locals/lib/index.js`
- 可执行脚本为 `bin/bird.js`

### 开发方向

当前的开发方向如下:

### Current:
- [] 加入 demo server 的功能 (罗心成, 王路远)
- [] 加入 generic 的 auth 插件

### Current Problems
- devtools 不再支持, 如 window.birdv2.changeUser('ccx')
- global 模式不再支持了

### 2016-05-27
- [x] 提高bird配置的可读性与有效性 (重构config的结构)
- [x] 实现配置文件的动态加载 (当前需要重新启动服务器)
- fix 一些常见的bug
    - [x] 如, debug: false的时候, 会影响所有其他正常的console.log输出
    - [x] 没有指定username, 则静默式退出
    - [x] 没有内网环境下, cheerio解析出错
- [x] 加入多一些合理的错误信息, 以方便用户调试和调整config
- [x] 快速生成本地 demo 的链接列表 @[  给其他人看的 demo  ]{c2i4y_gbr60jmp_iomwah1i}@
- [x] 引入 matriks 项目结构
- [x] 对代码组织进行简易重构

## 重构后的主要思路

- 关于config的自动更新
    - 利用 setInterval 和 fs.stat 来动态检测 config 变化, 更新 js 引用对象 config
    - 参见 @[  动态更新 config 对象  ]{t97zs_zd0tksdx_iom9u7yv}@
- 逻辑重构思路
    - bird的两大核心:
        - 设置好目标的后端 server, 并利用 httpClient 来进行接口转发
            - 接口转发的逻辑:
                - 1 得到 request 时, 获取其 pathname
                - 2 将 pathname 提交给 routes 解析函数, 得到一个资源处理策略
                - 3 根据资源处理策略来处理该 request
                - 4 如果为接口转发, 首先做一些简单的配置, 生成一个转发的必要对象: urlOptions
                - 5 通过 plugin (一般是用于解决用户身份验证, 得到cookie), 修改 urlOptions
                    - 参见 @[  解析所用的 plugin, 并调用它  ]{t97zs_vd7sdnis_iomf0g31}@
                - 6 将最终得到的 urlOptions 作为转发的参数, 发送 http 或 https 的请求到目标后端服务器
                - 7 截取所有后端服务器的返回进行处理
                - 8 如果后端返回是 3XX, 403 等特殊的跟身份验证相关的状态值, 需要考虑是否进行 plugin 的 retry
                    - 参见 @[  特殊返回的处理, 如 3XX, 403  ]{t97zs_w0fege8q_iomeynf7}@ 
                - 9 否则, 如果是其他的状态, 我们就全量的写到给前端的 reponse 里, 实现最终的接口转发
        - 通过 routes (路由设置) 来判定资源的返回方式
            - 目前有三种资源类别: mock (假数据), static (静态资源), forward (接口转发) 

[项目开发任务列表](./doc/tasks.md)


**注意: 以下的README内容为 birdv2 的范围, 请随时关注项目的开发**

## config
- bird的配制可是一个object,也可以是一个array, eg:


```
  var config = {
    name: 'ar',
    bird_port: 7676,
    staticFileRootDirPath: '../webapp',
    server: 'http://xx.xx.com:8901/ar/',
    uuap_server: 'http://xx.xx.com:8100',
    username: 'jay',
    password_suffix: ''
  };

  `or`
  var config = [{
    name: 'ar',
    bird_port: 7676,
    staticFileRootDirPath: '../webapp',
    server: 'http://xx.xx.com:8901/ar/',
    uuap_server: 'http://xx.xx.com:8100',
    username: 'jay',
    password_suffix: ''
  }, {
    name: 'ar2',
    bird_port: 7777,
    staticFileRootDirPath: '../webapp',
    server: 'http://xx.xx.com:8902/ar/',
    uuap_server: 'http://xx.xx.com:82S00',
    username: 'jay',
    password_suffix: ''
  }]
```


- 下面是详细的配制说明，*表示必须的配制， #表示正在开发或功能不稳定的配制， 其他是可选项
  
```
  // *服务名字,本配制以ar为例
  name: 'ar',
  // *服务端口
  bird_port: 3000,
  // *静态文件目录，可以为相对路径，如：../build
  staticFileRootDirPath: '/home/zp/work/ar/src/main/webapp/resources',
  // *测试机地址，是否带`ar`看环境的context
  server: 'http://xx-xx.epc:8901/ar/',
  // *该测试机对应的uuap地址
  uuap_server: 'http://uuap_test.com:8100',
  // *你想用谁登录
  username: 'who_you_want',
  // *密码后缀，没有就留空
  password_suffix: '',
  // 是否开启dev-tools(提供切换用户等功能)default:false
  dev_tool: {
    type: 'input', // #暂时只有这一个，后续加select
    top: 20,       // 工具上边距
    right: 20      //右边距
  },
  // feapps专用登录，hard code this one. default:false
  bprouting: 'bprouting/BpFlowRouting?appindex=true',
  // 是否使用静态的cookie,录bird出问题了你还可以把cookie粘到这里，像旧版一样default:false
  cookie: 'sessionid=XXXXXXXXXXX',
  // 转发路由，你可以将本地的请求转发到指定的路径
  router: {  
      '/ar': '/ar-web' // 将http://xx-xx.epc:8901/ar/XX/XX -> http://xx-xx.epc:8901/ar-web/XX/XX 
  },
  // 登录方式，默认是使用uuap来登录，加载auths/uuap.js default:'uuap'
  auth_standalone: 'uuap',
  // #当cookie效了重新cookie，当然，你可以重启bird来手动获取.default:true
  keep_alive: true,
  // #使用本地的数据，不转发. 当服务器当了，你可以造些假数据来本地测试
  use_local_data: {
    '/ar': '/your/data/path'
  }
```

## extendable

- 如果你的项目不是用uuap登录的，那你需要配制auth_standalone选项, 然后在auths/目录下添加上对应的js文件，当然你可以联系我，告诉你项目的地址 及登录帐号， 让我帮你加



## browser ci api

- 打开浏览器的console,可以执行以下命令：
- birdv2.use('uuap_name') 切换到其他用户登录

## notice

- 当获取的cookie失效时，如果response是重定向到其他url,bird会自动获取新cookie,并重定向回来，用户是感觉不到这个过程的。如果response是返回一个对象，使浏览器登出，跳转到 /logout，bird会根据request->header->referer又跳转回来，因为referer不包括锚点信息，对于angular用户会发现页面跳到默认页面；同理，手动点登出也会跳回来，只是换了个cookie


## todo

- track forward history??
- forwarding local json data

---
_Source: https://npm.io/package/birdv3 · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._