argos

package module
v0.0.0-...-da502f1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 14, 2026 License: MIT Imports: 7 Imported by: 0

README

argos

一份 IDL、一份业务实现，六种对外形态。

argos 是一个 Go 实验项目，用来验证一种 RPC 组合模型：协议不是框架里的枚举，而是 IDL、Transport、Codec 三者相乘的结果。

同一份 echo.proto、同一个 impl.go，可以同时对外提供 gRPC、REST/JSON、WebSocket、TCP/UDP 信封 RPC 和 Telnet 调试口。业务代码里不出现 http、grpc、ws 等传输名——选什么组合、监听哪个端口，只在启动服务的 main 里决定。

定位：证明「组合模型」能跑通，不是生产级 RPC 框架。真源是代码、测试与 AGENTS.md。

为什么做 argos

常见做法是「选框架 = 选协议」：gRPC 一套生成物，REST 再写一套，自有二进制协议又是一套。换对外形态往往意味着换栈或大量适配层。

argos 反过来问：如果协议只是三个正交维度的组合，会怎样？

维度 职责 例子
IDL 服务与方法签名、消息类型 protobuf（.proto）
Transport 网络通道：连接、路由、状态码写回 http2、http1、ws、tcp、udp、telnet
Codec 消息与字节的互转 protobuf、json

三者独立选配。例如 gRPC 并不是代码里的类型，而是 http2 + protobuf 按 gRPC 线缆约定实现之后，自然出现的行为——grpcurl 能调通，就是验收。

         ┌─ IDL ─────────── 方法名、Request/Response 类型
协议  =  ┼─ Transport ──── 怎么连、怎么路由、怎么收尾
         └─ Codec ─────────  body 怎么编解码

一张图看懂

  echo.proto          impl.go              main.go（你选组合）
      │                  │                      │
      ▼                  ▼                      ▼
  消息 + 桩代码      纯业务逻辑          Transport + Codec + 端口
      │                  │                      │
      └────────── RegisterEchoService ──────────┘
                              │
          ┌───────────────────┼───────────────────┐
          ▼                   ▼                   ▼
      :9090 gRPC          :8080 REST          :7000 TCP 信封
     (http2+protobuf)    (http1+json)       (tcp+protobuf)
          ...              ws / udp / telnet ...

一份 impl，注册多次 NewService，每次绑定不同的 Transport + Codec + 端口即可。

30 秒体验

环境：Go 1.27+

git clone https://github.com/argos-io/argos.git
cd argos
make verify          # 全量测试 + 六传输集成验收
go run example/echo/main.go   # 六端口 Echo 服务

起服务后，可用常见工具直接调用：

对外形态 端口 怎么试
gRPC (h2c) :9090 grpcurl -plaintext -proto example/echo/echo.proto -import-path example/echo -d '{"msg":"hi"}' localhost:9090 echo.v1.EchoService/Echo
REST/JSON :8080 curl -sS -X POST http://127.0.0.1:8080/echo.v1.EchoService/Echo -H 'Content-Type: application/json' -d '{"msg":"hi"}'
WebSocket / TCP / UDP / Telnet 见 main.go 端口 go test -run TestClientEchoSixTransports ./example/echo/...

完整示例与集成测试在 example/echo/。

写服务时长什么样

业务 impl——只依赖 protobuf 类型，不出现传输名：

func (s *echoImpl) Echo(ctx context.Context, req *EchoRequest) (*EchoResponse, error) {
    return &EchoResponse{Msg: "hello " + req.GetMsg()}, nil
}

启动——在 main 里选 Transport 和 Codec（可多端口、同一份 impl）：

import (
    "github.com/argos-io/argos"
    protobufcodec "github.com/argos-io/argos/codec/protobuf"
    "github.com/argos-io/argos/server"
    "github.com/argos-io/argos/transport/http2"
)

srv := server.New()
impl := echov1.NewEchoImpl()

svc := srv.NewService(
    argos.WithTransport(http2.New()),
    argos.WithListenAddress(":9090"),
    argos.WithCodec(protobufcodec.New()),
)
echov1.RegisterEchoService(svc, impl)

srv.Run(ctx)

客户端——生成桩提供 NewEchoServiceClient；地址用 WithTarget（内置 ip:// scheme）：

client := echov1.NewEchoServiceClient(
    argos.WithTarget("ip://127.0.0.1:9090"),
    argos.WithTransport(http2.New()),
    argos.WithCodec(protobufcodec.New()),
)
resp, _ := client.Echo(ctx, &echov1.EchoRequest{Msg: "hi"})

从 .proto 生成 message 与桩（内置 protocompile，无需系统安装 protoc）：

go run ./cmd/argos generate stub --from proto --proto-path . example/echo/echo.proto

内置组合一览

Transport 典型对外形态 流式 常见 Codec
http2 gRPC（h2c） ✅ protobuf
http1 REST unary json
ws WebSocket 信封 ✅ protobuf
tcp / udp 自有二进制信封 tcp ✅ / udp unary protobuf
telnet 行协议调试口 unary json

Filter（鉴权、日志等）在 Transport 之上、业务之下，服务端与客户端共用同一套类型。

仓库里有什么

区域 说明
server/ client/ 等 根包 argos 提供 With*；其余 API 在各子包
example/echo/ 可运行的六传输示例 + 协议验收测试
transport/ 六种传输实现
codec/ protobuf、json 编解码
cmd/argos/ CLI：generate stub、frontend list
internal/codegen/ IR、生成器、proto 前端

架构约束、开发流程、测试分层见 AGENTS.md。提交前推荐 make verify。

License

MIT

Documentation

Overview

Package argos holds shared configuration (WithTransport, WithCodec, …). Import subpackages for runtime types: client, server, stream, filter, errs, metadata, codec, transport.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type Config 

type Config struct {
	Transport transport.Transport
	Codec     codec.Codec

	Filters []filter.Filter

	ServerTransportOpts []transport.ServerOption
	ClientTarget        string
	ClientTransportOpts []transport.ClientOption
	// contains filtered or unexported fields
}

Config is one transport + codec + filter binding.

func NewConfig 

func NewConfig(opts ...Option) Config

NewConfig applies opts to a new Config.

func (*Config) CodecForCall 

func (c *Config) CodecForCall() (codec.Codec, error)

CodecForCall returns the Codec for an active call after Run has validated configuration.

func (*Config) ResolveCodec 

func (c *Config) ResolveCodec() (codec.Codec, error)

ResolveCodec returns the configured Codec, resolving a registered name on first use.

func (*Config) ResolveTransport 

func (c *Config) ResolveTransport() (transport.Transport, error)

ResolveTransport returns the configured Transport, resolving a registered name on first use.

func (*Config) ValidateCompatibility 

func (c *Config) ValidateCompatibility() error

ValidateCompatibility rejects combinations whose built-in wire protocol is tied to a particular codec. Unknown custom identities remain valid for opaque byte transports; restricted transports require a named codec so an accidental binary/text mismatch cannot silently corrupt a call.

type Option 

type Option func(*Config)

Option configures a Service or Client.

func WithClientMaxMessageSize 

func WithClientMaxMessageSize(size int64) Option

WithClientMaxMessageSize limits one encoded request or response message on the client side. Non-positive values use the transport default.

func WithClientTransportOption 

func WithClientTransportOption(opts ...transport.ClientOption) Option

WithClientTransportOption appends client dial/open options.

func WithCodec 

func WithCodec(v any) Option

WithCodec sets Codec from an instance or a registered name ("protobuf", ...). For a name, import the codec subpackage so init registers the factory.

Prefer WithCodecInstance or WithCodecNamed for compile-time checks.

func WithCodecInstance 

func WithCodecInstance[T codec.Codec](c T) Option

WithCodecInstance sets Codec from a concrete or interface value.

func WithCodecNamed 

func WithCodecNamed(name string) Option

WithCodecNamed sets Codec from a registered factory name.

func WithFilter 

func WithFilter(f filter.Filter) Option

WithFilter appends a Filter. Server and client share the same type.

func WithListenAddress 

func WithListenAddress(addr string) Option

WithListenAddress sets the server listen address (server only).

func WithMaxHeaderBytes 

func WithMaxHeaderBytes(size int) Option

WithMaxHeaderBytes limits HTTP request headers on transports that support the setting. Non-positive values use the transport default.

func WithMaxMessageSize 

func WithMaxMessageSize(size int64) Option

WithMaxMessageSize limits one encoded request or response message on the server side. Non-positive values use the transport default.

func WithServerTransportOption 

func WithServerTransportOption(opts ...transport.ServerOption) Option

WithServerTransportOption appends server listen options.

func WithTarget 

func WithTarget(target string) Option

WithTarget sets a client dial target (scheme://service-identifier, e.g. ip://127.0.0.1:9090).

func WithTransport 

func WithTransport(v any) Option

WithTransport sets Transport from an instance or a registered name ("http2", ...). For a name, import the transport subpackage so init registers the factory.

Go disallows interface types with methods in union constraints, so this accepts any and type-asserts at runtime. Prefer WithTransportInstance or WithTransportNamed for compile-time checks.

func WithTransportInstance 

func WithTransportInstance[T transport.Transport](t T) Option

WithTransportInstance sets Transport from a concrete or interface value.

func WithTransportNamed 

func WithTransportNamed(name string) Option

WithTransportNamed sets Transport from a registered factory name.

Source Files

View all Source files

Directories

Path Synopsis
Package client opens calls through one Transport and Codec.
 Package client opens calls through one Transport and Codec.
cmd
argos command
Command argos is the argos toolchain entrypoint.
 Command argos is the argos toolchain entrypoint.
Package codec converts messages to and from bytes.
 Package codec converts messages to and from bytes.
json
protobuf
Package errs defines argos status codes and errors.
 Package errs defines argos status codes and errors.
example
echo
Package filter wraps calls with cross-cutting handlers.
 Package filter wraps calls with cross-cutting handlers.
internal
cmd
Package cmd defines the argos CLI command tree.
 Package cmd defines the argos CLI command tree.
cmd/frontend
Package frontend defines argos frontend inspection subcommands.
 Package frontend defines argos frontend inspection subcommands.
cmd/generate
Package generate defines argos generate subcommands.
 Package generate defines argos generate subcommands.
codegen/check
Package check holds helpers for comparing generated Go source.
 Package check holds helpers for comparing generated Go source.
codegen/frontend
Package frontend converts IDL inputs into codegen IR.
 Package frontend converts IDL inputs into codegen IR.
codegen/frontend/execplugin
Package execplugin runs external IDL frontends that emit JSON IR on stdout.
 Package execplugin runs external IDL frontends that emit JSON IR on stdout.
codegen/frontend/irjson
Package irjson loads codegen IR from JSON files (handwritten or plugin output).
 Package irjson loads codegen IR from JSON files (handwritten or plugin output).
codegen/frontend/proto
Package proto parses .proto files into codegen IR using protocompile.
 Package proto parses .proto files into codegen IR using protocompile.
codegen/gen
Package gen renders ir.File into Go source (stub re-export).
 Package gen renders ir.File into Go source (stub re-export).
codegen/gen/message
Package message renders ir.File into *.pb.go or *.msg.go source.
 Package message renders ir.File into *.pb.go or *.msg.go source.
codegen/gen/stubgen
Package stubgen renders ir.File into *.argos.go source.
 Package stubgen renders ir.File into *.argos.go source.
codegen/ir
Package ir is the intermediate representation for argos stub generation.
 Package ir is the intermediate representation for argos stub generation.
codegen/stub
Package stub generates or checks *.argos.go and message files from IR.
 Package stub generates or checks *.argos.go and message files from IR.
limits
Package limits provides strict readers for untrusted message bodies.
 Package limits provides strict readers for untrusted message bodies.
statusmap
Package statusmap holds errs.Code ↔ wire status conversions for http1/http2.
 Package statusmap holds errs.Code ↔ wire status conversions for http1/http2.
wire
Package metadata carries key/value pairs outside the message body on context.
 Package metadata carries key/value pairs outside the message body on context.
Package selector resolves client targets by URI scheme into dial addresses.
 Package selector resolves client targets by URI scheme into dial addresses.
ip
Package ip registers the ip selector for direct host:port targets.
 Package ip registers the ip selector for direct host:port targets.
Package server binds transports and codecs to method dispatchers.
 Package server binds transports and codecs to method dispatchers.
Package stream is a decoded call stream.
 Package stream is a decoded call stream.
Package transport is the network layer: message boundaries, routing keys, and metadata on the wire.
 Package transport is the network layer: message boundaries, routing keys, and metadata on the wire.
http1
Package http1 implements unary Argos calls over HTTP/1.1.
 Package http1 implements unary Argos calls over HTTP/1.1.
http2
Package http2 implements gRPC-over-HTTP/2 (h2c) for Argos.
 Package http2 implements gRPC-over-HTTP/2 (h2c) for Argos.
tcp
Package tcp implements the Argos binary envelope over TCP.
 Package tcp implements the Argos binary envelope over TCP.
telnet
Package telnet implements a newline-framed text debug transport over TCP.
 Package telnet implements a newline-framed text debug transport over TCP.
udp
Package udp implements unary Argos calls over UDP.
 Package udp implements unary Argos calls over UDP.
ws
Package ws implements the Argos binary envelope over WebSocket (RFC6455).
 Package ws implements the Argos binary envelope over WebSocket (RFC6455).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.