README

Freddie

Freddie 是 Mercure Hub 规范的 PHP 实现。

它非常快，建立在巨人的肩膀上

• PHP 8.1
• Framework X 和 ReactPHP
• Symfony 6
• Redis（可选）。

查看已覆盖和尚未覆盖的功能 这里。

安装

运行中心需要 PHP 8.1+。

作为一个独立的 Mercure 中心

composer create-project freddie/mercure-x freddie && cd freddie
bin/freddie

这将在 127.0.0.1:8080 上启动 Freddie 实例，并启用匿名订阅。

您可以通过使用带有 !ChangeMe! 密钥并使用 HMAC SHA256 算法签名的有效 JWT 向中心发布更新。

要更改这些值，请参阅 安全性。

作为现有 Symfony 应用的捆绑包

composer req freddie/mercure-x

然后，您可以执行以下操作来启动中心

bin/console freddie:serve

您可以在 .env.local 中覆盖相关环境变量，并在您的 config/services.yaml 中覆盖服务，就像平常一样。

然后，您可以在服务中注入 Freddie\Hub\HubInterface，以便您可以通过 $hub->publish($update) 调用，或在 CLI 环境中监听已分发的更新。

请注意，这仅在使用 Redis 传输时才有效。

⚠️ Freddie 使用自己的路由/身份验证系统（因为异步/事件循环）。

它公开的控制器不能导入到您的 routes.yaml 中，并且超出了您的 security.yaml 范围。

使用方法

./bin/freddie

它将在 127.0.0.1:8080 上启动一个新的 Mercure 中心。要更改此地址，请使用 X_LISTEN 环境变量

X_LISTEN="0.0.0.0:8000" ./bin/freddie

安全性

默认 JWT 密钥是 !ChangeMe! 并带有 HS256 签名。

您可以通过更改环境变量来设置不同的值（在 .env.local 或操作系统级别）：X_LISTEN、JWT_SECRET_KEY、JWT_ALGORITHM、JWT_PUBLIC_KEY 和 JWT_PASSPHRASE（当使用 RS512 或 ECDSA 时）

请参阅 Mercure 规范的 授权 部分，以作为发布者或订阅者进行身份验证。

PHP 传输（默认）

默认情况下，中心将作为简单的事件调度程序在单个 PHP 进程中运行。

它可以满足基本使用需求，但使用此传输会阻止可扩展性，因为打开另一个进程不会共享相同的事件发射器。

只要

• 您不期望每秒超过数百个更新
• 您的应用程序从一个服务器提供。

Redis 传输

另一方面，您可以使用 Redis 传输在 多个端口 和/或 多个服务器 上启动中心（只要它们共享相同的 Redis 实例），并可选地使用负载均衡器来分发流量。

中心的 官方开源版本 由于 bolt 传输的并发限制不允许扩展。

要使用Redis传输启动中心，请更改TRANSPORT_DSN环境变量

TRANSPORT_DSN="redis://127.0.0.1:6379" ./bin/freddie

您可以在DSN的查询字符串中传递的可选参数

• pingInterval - 定期ping Redis连接，有助于检测故障（默认2.0）
• readTimeout - ping或发布请求的最大持续时间（默认0.0：视为禁用）

或者，您可以将此变量设置为.env.local。

优势和限制

此实现不提供SSL和HTTP2终止，因此您最好在其前面放置一个反向代理。

示例Nginx配置

upstream freddie {
    # Example with a single node
    server 127.0.0.1:8080;

    # Example with several nodes (they must share the same Redis instance)
    # 2 instances on 10.1.2.3
    server 10.1.2.3:8080;
    server 10.1.2.3:8081;

    # 2 instances on 10.1.2.4
    server 10.1.2.4:8080;
    server 10.1.2.4:8081;
}

server {
    
    listen 443 ssl http2;
    listen [::]:443 ssl http2;
    server_name example.com;

    ssl_certificate /etc/ssl/certs/example.com/example.com.cert;
    ssl_certificate_key /etc/ssl/certs/example.com/example.com.key;
    ssl_ciphers EECDH+CHACHA20:EECDH+AES128:RSA+AES128:EECDH+AES256:RSA+AES256:EECDH+3DES:RSA+3DES:!MD5;

    location /.well-known/mercure {
        proxy_pass http://freddie;
        proxy_read_timeout 24h;
        proxy_http_version 1.1;
        proxy_set_header Connection "";
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

示例Caddy配置

单节点

example.com

reverse_proxy 127.0.0.1:8080

多节点

example.com

reverse_proxy 10.1.2.3:8080 10.1.2.3:8081 10.1.2.4:8080 10.1.2.4:8081

有效载荷限制

⚠ 在Framework-X中存在已知限制，防止请求体重量超过64 KB。由于Framework-X封装了HTTP服务器实例化，因此在撰写本文时，此限制无法提升。

通过HTTP（至少是通过HTTP）向Freddie发布更大的更新可能会导致400错误。

功能覆盖范围

测试

此项目100%由Pest测试覆盖。

composer tests:run

贡献

如果您想改进此项目，请随时提交PR

• CI将在您不遵循PSR-12编码标准时发出警告
• 在新增功能的情况下，必须附带测试
• 必须通过8级PHPStan分析

在提交之前，您可以运行以下命令以确保所有CI要求都已成功满足

composer ci:check

许可证

GNU通用公共许可证v3.0。