{"id":15287498,"url":"https://github.com/liftbridge-io/liftbridge-api","last_synced_at":"2025-04-13T05:37:08.133Z","repository":{"id":43127822,"uuid":"139086645","full_name":"liftbridge-io/liftbridge-api","owner":"liftbridge-io","description":"Protobuf definitions for the Liftbridge gRPC API. https://github.com/liftbridge-io/liftbridge","archived":false,"fork":false,"pushed_at":"2022-11-23T15:10:47.000Z","size":844,"stargazers_count":14,"open_issues_count":3,"forks_count":13,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-26T22:12:25.899Z","etag":null,"topics":["api","client","cloud-native","grpc","liftbridge","messaging","nats","protobuf","pubsub","streaming"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/liftbridge-io.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-29T01:36:48.000Z","updated_at":"2025-01-13T03:04:13.000Z","dependencies_parsed_at":"2023-01-21T17:45:13.170Z","dependency_job_id":null,"html_url":"https://github.com/liftbridge-io/liftbridge-api","commit_stats":null,"previous_names":["liftbridge-io/liftbridge-grpc"],"tags_count":16,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liftbridge-io%2Fliftbridge-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liftbridge-io%2Fliftbridge-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liftbridge-io%2Fliftbridge-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/liftbridge-io%2Fliftbridge-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/liftbridge-io","download_url":"https://codeload.github.com/liftbridge-io/liftbridge-api/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248670508,"owners_count":21142897,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","client","cloud-native","grpc","liftbridge","messaging","nats","protobuf","pubsub","streaming"],"created_at":"2024-09-30T15:29:35.521Z","updated_at":"2025-04-13T05:37:08.105Z","avatar_url":"https://github.com/liftbridge-io.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Liftbridge API\n\nThis repository contains the public API definitions for\n[Liftbridge](https://github.com/liftbridge-io/liftbridge). It is primarily\nintended for Liftbridge client developers.\n\n## gRPC API\n\nThe client-facing gRPC API is defined in [api.proto](api.proto).\n\n## Direct NATS API\n\nIt is also possible for a client to publish messages to Liftbridge via NATS\ndirectly. Liftbridge accepts plain NATS messages, allowing it to make existing\nsubjects durable without any publisher changes. However, these messages will\nnot have some features such as acks.\n\nIn order to opt into Liftbridge-specific features, the message must be prefixed\nwith the following header and be encoded as a `Message` (defined in\n[api.proto](api.proto)).\n\n### Liftbridge Envelope Header\n\nAll Liftbridge messages and RPCs sent over NATS are prefixed with an envelope\nheader. This includes client-facing messages, such as publishes and acks, as\nwell as internal RPCs like replication.\n\n```\n0               8               16              24              32\n├───────────────┴───────────────┴───────────────┴───────────────┤\n│                          Magic Number                         │\n├───────────────┬───────────────┬───────────────┬───────────────┤\n│    Version    │   HeaderLen   │     Flags     │    MsgType    │\n├───────────────┴───────────────┴───────────────┴───────────────┤\n│                       CRC-32C (optional)                      │\n└───────────────────────────────────────────────────────────────┘\n```\n\n#### Magic number [4 bytes]\n\nThe Liftbridge magic number is `B9 0E 43 B4`. This was chosen by random but\ndeliberately restricted to invalid UTF-8 to reduce the chance of a collision.\nThis was also verified to not match known file signatures.\n\n#### Version [1 byte]\n\nThe version byte allows for future protocol upgrades. This should only be\nbumped if the envelope format changes or if the message encoding changes in a\nnon-backwards-compatible way. Adding fields to the messages should not require\na version bump.\n\nCurrently, the only supported protocol version is v0, i.e. `0x00`.\n\n#### HeaderLen [1 byte]\n\nThe header length is the offset of the payload. This is included primarily for\nsafety.\n\n#### Flags [1 byte]\n\nThe flag bits are defined as follows:\n\n| Bit | Description     |\n| :-- | :-------------- |\n| 0   | CRC-32C enabled |\n\n#### MsgType [1 byte]\n\nThis is the Liftbridge-specific message type the envelope contains:\n\n| MsgType | Name                      | Description                                            | Internal |\n| :------ | :------------------------ | :----------------------------------------------------- | :------- |\n| 0       | Publish                   | Client-published message                               | no       |\n| 1       | Ack                       | Server-published ack                                   | no       |\n| 2       | ReplicationRequest        | Request to replicate partition data                    | yes      |\n| 3       | ReplicationResponse       | Response to ReplicationRequest                         | yes      |\n| 4       | RaftJoinRequest           | Request to join Raft cluster                           | yes      |\n| 5       | RaftJoinResponse          | Response to RaftJoinRequest                            | yes      |\n| 6       | LeaderEpochOffsetRequest  | Request for partition leader's latest offset for epoch | yes      |\n| 7       | LeaderEpochOffsetResponse | Response to LeaderEpochOffsetRequest                   | yes      |\n| 8       | PropagatedRequest         | Request forwarded to metadata leader                   | yes      |\n| 9       | PropagatedResponse        | Response to PropagatedRequest                          | yes      |\n| 10      | ServerInfoRequest         | Request for cluster information                        | yes      |\n| 11      | ServerInfoResponse        | Response to ServerInfoRequest                          | yes      |\n| 12      | PartitionStatusRequest    | Request to get partition status                        | yes      |\n| 13      | PartitionStatusResponse   | Response to PartitionStatusRequest                     | yes      |\n| 14      | PartitionNotification     | Signal new data is available for partition             | yes      |\n\n#### CRC-32C [4 bytes, optional]\n\nThe CRC-32C (Castagnoli) is the checksum of the payload (i.e. from HeaderLen to\nthe end). This is optional but should significantly reduce the chance that a\nrandom NATS message is interpreted as a Liftbridge message.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliftbridge-io%2Fliftbridge-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fliftbridge-io%2Fliftbridge-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fliftbridge-io%2Fliftbridge-api/lists"}