artisan-build/matte-contracts
Composer 安装命令：
composer require artisan-build/matte-contracts
包简介
The versioned contracts shared between matte-client and matte-server.
关键字：
README 文档
README
The versioned HTTP wire protocol shared between
matte-client (the send side) and
matte-server (the receive side) of
Matte — self-hosted, unmetered image background
removal on Laravel Cloud.
This package is tiny and deliberately so. It has zero Laravel dependencies — just typed
PHP 8 DTOs, the enums, and the ENVELOPE_VERSION constant. It is the single place Matte's
wire compatibility lives, and because Matte's server is a plain HTTP API, it doubles as a
public contract: any consumer in any language can implement against it.
Read-only mirror. This repository is a read-only split of the
artisan-build/mattemonorepo. Issues and pull requests are disabled here — please open them on the monorepo.
Why a separate package
Across many independently-deployed consumers and one self-hosted server, version skew is the normal state, not an error. You cannot keep them in lockstep, so the protocol is built to tolerate skew, and the contract that defines it lives in exactly one place that both sides pin. Keeping it framework-free means the wire shapes don't drag the Laravel runtime into a non-Laravel consumer.
The compatibility rules
- The envelope carries its own version. Every payload includes
ENVELOPE_VERSION. - Additive within a major. New fields are optional and added; existing fields are never removed or repurposed. That one rule is what lets a newer server parse every older envelope.
- A version newer than the server fails loud. The server returns a clear 4xx for an envelope it doesn't understand yet — "your client is ahead of this Matte instance."
- The image bytes are opaque. They cross the wire as multipart, never inside the envelope; only the thin options/status metadata is version-sensitive.
- A major bump is a deliberate act — an explicit
composer require, never a routinecomposer update.matte-clientpins a caret constraint (^X) on this package.
The envelopes (shape)
Submit (POST /v1/remove): the image is sent as multipart bytes; this envelope is the
options/metadata beside it.
| Field | Meaning |
|---|---|
envelope_version |
The ENVELOPE_VERSION the client was built against. |
options.mode |
ml or grabcut. |
options.preset |
fast | balanced | quality. |
options.model / edge_mode / iterations / margin |
Optional tuning. |
idempotency_key / callback_url |
Optional. |
Status (GET /v1/jobs/{id}):
| Field | Meaning |
|---|---|
envelope_version |
The server's envelope major. |
job_id |
The job identifier. |
status |
queued | processing | done | failed. |
output_ref |
Storage key of the transparent PNG (when done). |
error |
Failure reason (when failed). |
The package ships these as readonly DTOs (RemovalRequest, RemovalOptions,
JobStatusEnvelope), the backing enums (Mode, Preset, EdgeMode, JobStatus), a
Protocol version helper, and an InvalidEnvelope exception — with tolerant fromArray
(ignores unknown keys, defaults absent ones).
Installation
composer require artisan-build/matte-contracts
You usually don't install this directly — it arrives as a dependency of matte-client or
matte-server.
License
MIT. See LICENSE.
统计信息
- 总下载量： 0
- 月度下载量： 0
- 日度下载量： 0
- 收藏数： 0
- 点击次数： 1
- 依赖项目数： 2
- 推荐数： 0
其他信息
- 授权协议： MIT
- 更新时间： 2026-06-14