PlainApp
API 参考

设备间 GraphQL

已配对设备之间的签名加密请求。

key = Base64Decode(peer.key)已配对设备;c-id = senderClientId

客户端
https://<host>:<port>/peer_graphql
服务端

POST /peer_graphql

c-id: 706c6169-3b80-8f42-9a61-4e312e54d001

HTTP · binary

JSON({ signature, requestId, query, variables })

执行前先验证设备签名。UUIDv7 时间窗口 ±60 秒,持久化去重。

XChaCha20-Poly1305 · 悬停或点按字段
1 / 2

防重放

requestId = UUIDv7()JSON { signature, requestId, query, variables } → authenticated encryption
↓ POST /peer_graphql
认证并解密peer.key / channel.key + Ed25519✕ → 拒绝
↓
校验 UUIDv7 时间|serverTime − requestId timestamp| ≤ 60 s✕ → 拒绝
↓
执行前记录 requestIdSQLite: peer_graphql:channelId + senderClientId + requestId
✓ ↓执行 GraphQL
✕ ↓拒绝重复的 requestId
库调用示例

Core 代码节选,设备直连模式(不带 c-cid)。

text
// plain-rs/src/infrastructure/transport/contract.rs
let payload = contract::signed_request(&signing_keypair, query, variables, "")?;
let request_body = http_request::encrypt_raw(
    &peer_key, "POST", "/peer_graphql", payload.as_bytes(),
).ok_or("encrypt failed")?;
let response = transport.post(url, &client_id, None, &request_body).await?;
let plaintext = http_response::Context::new(&request_body)
    .decrypt(&peer_key, &response).ok_or("invalid response")?;

HTTP 403:设备未配对。401:未知设备、解密或签名失败。400:信封格式错误、过期或重复。

类型定义

graphql
enum ChannelSystemMessageType {
	INVITE
	INVITE_ACCEPT
	INVITE_DECLINE
	UPDATE
	KICK
	LEAVE
}

type ChatAttachment {
	id: ID!
	uri: String!
	size: Long!
	durationMs: Long!
	width: Int!
	height: Int!
	summary: String!
	fileName: String!
}

enum ChatAttachmentType {
	IMAGE
	FILE
}

union ChatContent = ChatMessageContent | ChatShareContent

type ChatDeliveryResult {
	peerId: ID!
	peerName: String!
	error: String
}

type ChatItem {
	"""
	`me` when this device created the item, otherwise the client id of
	the originating peer.
	"""
	fromId: ID!
	"""
	Peer id for direct messages; empty for channel messages —
	`channelId` is authoritative there.
	"""
	toId: ID!
	"""
	Null for direct messages: the store keeps "" and the contract says
	null, because "" is not a channel a client can query.
	"""
	channelId: ID
	id: ID!
	content: ChatContent!
	createdAt: Instant!
	updatedAt: Instant!
	status: ChatStatus!
	deliveryResults: [ChatDeliveryResult!]!
}

type ChatLinkPreview {
	url: String!
	title: String
	description: String
	image: String
	imageWidth: Int!
	imageHeight: Int!
	siteName: String
	domain: String
	createdAt: Instant!
}

type ChatMessageAttachment {
	type: ChatAttachmentType!
	attachment: ChatAttachment!
}

type ChatMessageContent {
	text: String
	format: ChatTextFormat!
	items: [ChatMessageAttachment!]!
	linkPreviews: [ChatLinkPreview!]!
}

type ChatShareContent {
	shareId: ID!
	urlToken: String!
	peerInfo: ChatSharePeer!
	name: String!
	itemCount: Long!
	totalSize: Long!
	expiresAt: Instant
}

type ChatSharePeer {
	id: ID!
	ip: String!
	port: Int!
}

enum ChatStatus {
	SENT
	FAILED
	PARTIAL
	PENDING
}

enum ChatTextFormat {
	PLAIN
	MARKDOWN
}

scalar Instant

scalar Long

type Mutation {
	createChatItem(content: String!): [ChatItem!]!
	channelSystemMessage(type: ChannelSystemMessageType!, payload: String!): Boolean!
	startAware: Boolean!
}

enum PeerStatus {
	PAIRED
	UNPAIRED
	CHANNEL
}

type Query {
}

"""
Directs the executor to include this field or fragment only when the `if` argument is true.
"""
directive @include(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
"""
Directs the executor to skip this field or fragment when the `if` argument is true.
"""
directive @skip(if: Boolean!) on FIELD | FRAGMENT_SPREAD | INLINE_FRAGMENT
schema {
	query: Query
	mutation: Mutation
}