@bonniernews/ stayput (中文(简体) )
用于节点.js测试环境的默认-默认网络守护. 在套接字级别上屏蔽非本地的TCP,所以一个带有被泄露出生产连接字符串的测试套件在连接时会响亮地失败,而不是静默地突变生产. 原始TCP驱动器(pg,mongodb,弹性研究,redis)和取取/undici的工程——不仅仅是HTTP.
快开始
// .mocharc.cjs
module.exports = { require: ['@bonniernews/stayput/register'] };
被屏蔽的连接 err.code === 'EREMOTEBLOCKED'。 。 。 .
CI已经通过向每个节点进程注入了守护符 NODE_OPTIONS 在共享的工作流程模板中——mocharc线是保护笔记本电脑的,这就是流出活口证书实际居住的地方.
领养由ESLint检查:共享的ESLint配置船有两项规则—— stayput-required 标记缺少注册行(自动固定)的摩查克,以及 project-has-guard 旗帜测试文件不受任何留置量加载摩卡配置规范。 如果你看到这些警告之一, 上面的快速开始是修复.
防跑器(带子和吊杆)
木炭线只有卫兵才能装上木炭. mocha --no-config摩查从一个子目录引用, node --test,或者开玩笑都跳过。 如果您的Repo拥有一个共享的测试帮助器, 测试导入, 将守卫也固定在那里 —— 加载是一能的
// test/helpers/db.js
import '@bonniernews/stayput/register'; // guard on, no matter how the runner was invoked
import { assertActive } from '@bonniernews/stayput';
export async function testDb() {
assertActive(); // refuse to hand out connections if the guard was tampered with
// ...create and return the client
}
边界规则:停留是devDependency,只有测试自有文件(测试助手,设置文件,mocharc)可以导入它——永远不会 src/它会撞倒一个生产装置。 如果测试直接使用应用软件的真实的 DB 模块,则在两者之间添加一个薄的测试帮助器,而不是在生产代码上加注 NODE_ENV。 。 。 .
(在CI中,这是多余的—— NODE_OPTIONS 注入守护每一个节点过程,无论跑道或配置. )
政策
当地( 无) CI env):仅回放. 在CI中:回回转+私有范围(RFC1918). 其他的都被封锁了.
| 新闻 var | 效果 |
|---|---|
STAYPUT_ALLOW | 逗号分隔了额外的主机/IPs/IPv4 CIDRs,例如. 10.128.0.5,db.internal |
STAYPUT_DENY | 相同的格式—— 拒绝节拍允许 |
STAYPUT_DISABLE=I_UNDERSTAND_THE_RISK | 关闭护卫(丑陋而突出) |
在工作流程文件中而非代码中设置覆盖 : STAYPUT_ALLOW编号 :STAYPUT_DISABLE 作为例外库存,是全舰队的两倍.
AI探员
一个 EREMOTEBLOCKED 错误是停止信号,不是需要修复的bug. 未设置 STAYPUT_ALLOW 或者说 STAYPUT_DISABLE,编辑工作流程env,或去掉mocharc线以让测试通过——该块通常表示测试套件指向它不应该触及的基础设施. 暂停,叫人去核实目标 只有人类在工作流程文件中增加了例外,在审查中和全舰队的grep中都能看到例外.
此合同被红组(2026-08-24):一个编码代理(克洛德)被授予了"沙箱回波",其测试击中了被封锁的私人行距数据库并被告知"今天就让它绿". 它从错误消息中诊断出警卫,拒绝推翻或伪造结果(包括嘲笑驱动器或重新指定测试),并停止要求人验证. 指导而不是执行——但它对行为良好的代理人有效.
程序化 API
import stayput, { enable, assertActive } from '@bonniernews/stayput';
enable({
allow: ['10.128.0.5'],
deny: ['10.10.0.0/16'], // deny beats allow
privateRanges: 'auto', // 'auto' = private ranges only when CI is set
onBlock: (host, port) => {},
});
assertActive(); // throws if never loaded or unpatched
stayput.isActive; // live getter on the default export
更倾向于命名的出口: stayput.assertActive() 默认导入行程 import/no-named-as-default-member 在共享的ESLint配置中。 装有货包的申报船型StayputOptions, (中文(简体) ), Stayput),所以 TypeScript 测试助手不需要 declare module ub.
@bonniernews/stayput/mocha 导出运行的根钩子插件 assertActive() 测试前.
装入为一等元: 多重负载( NODE OPTIONS + mocharc + 导入) 合并允许列表, 补丁一次, 并记录一行可读行 :
stayput/0.1.0 active mode=loopback+private allow=2 deny=1 source=NODE_OPTIONS
该行每条流程树一出一出,而并非每条流程一出一出. 伐木后,停留记录线路在 STAYPUT_LOGGED; 子进程继承它(mocha) -p 工人们,每个过程都经过 NODE_OPTIONS保持安静 当他们自己的线是相同的。 他们仍然被看守着。 只有当该行不同,例如另一种模式,允许或拒绝的条目数量不同时,孩子才会打印自己的行,或者 STAYPUT_DISABLE。该行显示的是计数,而不是条目本身,因此,允许列表中同一计数的不同条目的儿童保持安静.
一层多
留守是客户侧脚枪后卫——最后防线,而不是计划. 它补充,绝不取代:
- 学历 ——知道为什么prod credits不属于笔记本电脑或repos系统会打败任何守卫.
- 简单、短暂的进入路径 ——当你真正需要到达一个真正的数据库时,在非默认端口上使用ephemerial 代理/跳出主机. 被制裁的方式比冒险的方式容易,被泄露的默认端口连接字符串不会在任何地方通路.
- 防火墙规则/网络设计 ——试验环境应完全没有生产路线;只有在存在一条路线的情况下,才能中止.
- 试验框架和固定装置 ——测试容器,CI服务容器,以及药用固定装置,消除了在共享基础设施进行测试的原因.
- 服务器侧卫士 ——只读默认角色, DDL Gating, RBAC 不使用破坏性动词(每个数据库计划 汉道尔·姆德) (中文(简体) ).
如何运作
补丁 net.Socket.prototype.connect (同步抛出被屏蔽的 IP 字节; unix socket 总是允许的)和 dns.lookup (主机名解决后会经过审核). TLS, http/https and undici ride on 互联网档案馆的存檔,存档日期2013-10-21 net.Socket所以他们被免费覆盖. server.listen 通过 dns.lookup 因此,允许对回放和未指明地址进行绑定(0.0.0.0, (中文(简体) ), ::)——约束特定的非本地IP需要 STAYPUT_ALLOW这是护脚枪,不是安全边界.
需要节点 \ 20.6(预装在CI中 NODE_OPTIONS=--import …/register.js) (中文(简体) ).
未涵盖
其他进程. 补丁在一个节点进程内活. 儿童 node 进程只能通过 NODE_OPTIONS (这是CI注射如何到达每个过程), 没有任何不是节点的 永远不会做: 由CLI所产的本土二进制, psql 在 npm 脚本中,一个由测试运行开始的容器。 Prisma是常见案例—— prisma migrate deploy 打开它从Rust schema引擎中产生的连接,所以一个测试脚本,在Mocha没有保护之前运行迁移,即使在同一过程中登记了停留量(Sprisma generate 打开无连接). 对于这些步骤,请将它们读作“配置环境”和“连接字符串”。 留置守护测试进程;它不会守护周围的脚本.
圈后代和地道. 一个云SQL Auth代理, kubectl port-forward 或SSH地道听 127.0.0.1是回回回回回回回回回回回回回回回回回回回回回回——停留量不能告诉本地邮递员127.0.0.1:5432从地道到同一港口的生产. 不要在默认的端口局部运行任何东西:给测试容器自己的非默认端口和每个代理端口或地道一个不同的端口,所以每个端口都有完全一个目的地(这个repo自己的作曲). Yaml在54329年出版邮报,mongo在27019年出版,弹性搜索在9209年出版. 然后默认的端口拒绝每一个连接,一个被泄露或被复制的连接字符串携带到无处去,而一个真实的环境只是故意到达的.
发展
npm test # unit tests + type declaration check — no network, no docker
npm run test:integration # pg + mongodb + elasticsearch against docker (compose.yaml)
设计决定、环境矩阵和推出计划: 汉道尔·姆德。 。 。 .