Feat: Initial implementation — pull-based HTTP event feeds

.github/ISSUE_TEMPLATE/bug.yaml

@@ -0,0 +1,83 @@
+name: "🐛 Bug Report"
+description: "Submit a bug report to help us improve"
+title: "🐛 Bug Report: "
+labels: [bug]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out our bug report form 🙏
+  - type: textarea
+    id: steps-to-reproduce
+    validations:
+      required: true
+    attributes:
+      label: "👟 Reproduction steps"
+      description: "How do you trigger this bug? Please walk us through it step by step."
+      placeholder: "When I ..."
+  - type: textarea
+    id: expected-behavior
+    validations:
+      required: true
+    attributes:
+      label: "👍 Expected behavior"
+      description: "What did you think would happen?"
+      placeholder: "It should ..."
+  - type: textarea
+    id: actual-behavior
+    validations:
+      required: true
+    attributes:
+      label: "👎 Actual Behavior"
+      description: "What did actually happen? Add screenshots, if applicable."
+      placeholder: "It actually ..."
+  - type: dropdown
+    id: utopia-version
+    attributes:
+      label: "🎲 Utopia Abuse version"
+      description: "What version of Utopia Abuse are you running?"
+      options:
+        - Version 0.6.x
+        - Version 0.5.x
+        - Version 0.4.x
+        - Version 0.3.x
+        - Version 0.2.x
+        - Version 0.1.x
+        - Different version (specify in environment)
+    validations:
+      required: true
+  - type: dropdown
+    id: operating-system
+    attributes:
+      label: "💻 Operating system"
+      description: "What OS is your server / device running on?"
+      options:
+        - Linux
+        - MacOS
+        - Windows
+        - Something else
+    validations:
+      required: true
+  - type: textarea
+    id: enviromnemt
+    validations:
+      required: false
+    attributes:
+      label: "🧱 Your Environment"
+      description: "Is your environment customized in any way?"
+      placeholder: "I use Cloudflare for ..."
+  - type: checkboxes
+    id: no-duplicate-issues
+    attributes:
+      label: "👀 Have you spent some time to check if this issue has been raised before?"
+      description: "Have you Googled for a similar issue or checked our older issues for a similar bug?"
+      options:
+        - label: "I checked and didn't find similar issue"
+          required: true
+  - type: checkboxes
+    id: read-code-of-conduct
+    attributes:
+      label: "🏢 Have you read the Code of Conduct?"
+      options:
+        - label: "I have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/HEAD/CODE_OF_CONDUCT.md)"
+          required: true

.github/ISSUE_TEMPLATE/documentation.yaml

@@ -0,0 +1,32 @@
+name: "📚 Documentation"
+description: "Report an issue related to documentation"
+title: "📚 Documentation: "
+labels: [documentation]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to make our documentation better 🙏
+  - type: textarea
+    id: issue-description
+    validations:
+      required: true
+    attributes:
+      label: "💭 Description"
+      description: "A clear and concise description of what the issue is."
+      placeholder: "Documentation should not ..."
+  - type: checkboxes
+    id: no-duplicate-issues
+    attributes:
+      label: "👀 Have you spent some time to check if this issue has been raised before?"
+      description: "Have you Googled for a similar issue or checked our older issues for a similar bug?"
+      options:
+        - label: "I checked and didn't find similar issue"
+          required: true
+  - type: checkboxes
+    id: read-code-of-conduct
+    attributes:
+      label: "🏢 Have you read the Code of Conduct?"
+      options:
+        - label: "I have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/HEAD/CODE_OF_CONDUCT.md)"
+          required: true

.github/ISSUE_TEMPLATE/feature.yaml

@@ -0,0 +1,40 @@
+name: 🚀 Feature
+description: "Submit a proposal for a new feature"
+title: "🚀 Feature: "
+labels: [feature]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for taking the time to fill out our feature request form 🙏
+  - type: textarea
+    id: feature-description
+    validations:
+      required: true
+    attributes:
+      label: "🔖 Feature description"
+      description: "A clear and concise description of what the feature is."
+      placeholder: "You should add ..."
+  - type: textarea
+    id: pitch
+    validations:
+      required: true
+    attributes:
+      label: "🎤 Pitch"
+      description: "Please explain why this feature should be implemented and how it would be used. Add examples, if applicable."
+      placeholder: "In my use-case, ..."
+  - type: checkboxes
+    id: no-duplicate-issues
+    attributes:
+      label: "👀 Have you spent some time to check if this issue has been raised before?"
+      description: "Have you Googled for a similar issue or checked our older issues for a similar bug?"
+      options:
+        - label: "I checked and didn't find similar issue"
+          required: true
+  - type: checkboxes
+    id: read-code-of-conduct
+    attributes:
+      label: "🏢 Have you read the Code of Conduct?"
+      options:
+        - label: "I have read the [Code of Conduct](https://github.com/appwrite/appwrite/blob/HEAD/CODE_OF_CONDUCT.md)"
+          required: true

.github/workflows/analysis.yml

@@ -0,0 +1,25 @@
+name: "Static analysis"
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  check:
+    name: PHPStan
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      # Run against the test image rather than a bare composer container: the
+      # Redis stream calls only resolve where ext-redis is actually installed.
+      - name: Build
+        run: |
+          docker compose build tests
+          docker compose up -d tests
+
+      - name: Run PHPStan
+        run: docker compose exec -T tests composer check

.github/workflows/linter.yml

@@ -0,0 +1,25 @@
+name: "Linter"
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  lint:
+    name: Linter
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      # The project's own image, as the analysis job uses: pint needs a PHP
+      # new enough to parse 8.5 syntax, which `composer:latest` does not pin.
+      - name: Build
+        run: |
+          docker compose build tests
+          docker compose up -d tests
+
+      - name: Run Linter
+        run: docker compose exec -T tests composer lint

.github/workflows/tests.yml

@@ -0,0 +1,54 @@
+name: "Tests"
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  tests:
+    name: "PHP ${{ matrix.php-versions }} · ${{ matrix.suite }}"
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Add a PHP version here and nowhere else — the image is built from one
+        # parameterized Dockerfile.
+        php-versions: ['8.5']
+        # One job per adapter: each runs the same behaviour scenarios
+        # (tests/Feed/*/Base.php), so a green suite means that adapter honours
+        # the whole contract. See phpunit.xml for what each suite contains.
+        suite: [unit, memory, cache, http, redis, pool]
+
+    env:
+      PHP_VERSION: ${{ matrix.php-versions }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - name: Build
+        run: |
+          docker compose build
+          docker compose up -d
+
+      - name: Run ${{ matrix.suite }} tests
+        run: docker compose exec -T tests vendor/bin/phpunit --testsuite ${{ matrix.suite }}
+
+  coverage:
+    name: Coverage
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - name: Build
+        run: |
+          docker compose build
+          docker compose up -d
+
+      # Every suite, so the Redis and pooled adapters count too. No threshold
+      # yet — the number is there to be read.
+      - name: Report coverage
+        run: docker compose exec -T tests composer coverage:all

.gitignore

@@ -0,0 +1,6 @@
+/vendor/
+/.idea/
+coverage.xml
+.phpunit.cache/
+.phpunit.result.cache
+.DS_Store

CHANGELOG.md

@@ -0,0 +1,107 @@
+# Changelog
+
+## 0.1.0 — Initial release
+
+Pull-based HTTP event feeds ([http-feeds.org](https://www.http-feeds.org/)) for
+PHP. A producer writes events to an ordered log; each consumer polls for what
+happened after the last event it handled, and keeps that position itself.
+
+Requires PHP 8.5. `ext-redis` is a suggestion, needed only by the Redis and
+pooled adapters.
+
+### Producing
+
+- `Producer` — `produce(type, data, subject)` for the common case, and
+  `publish(CloudEvent)` for a prepared event. Both return the event's id, which
+  is also its position in the feed. The producer stamps its own `source`, the
+  store assigns the `id`, and a missing `time` becomes now; everything else is
+  published as prepared.
+- Events are [utopia-php/cloudevents](https://github.com/utopia-php/cloudevents)
+  `CloudEvent` objects. This library defines no event type of its own, so a feed
+  event is accepted anywhere a `CloudEvent` is, and `datacontenttype`,
+  `dataschema` and extension attributes survive an append and a read.
+
+### Serving
+
+- `Server` — the feed endpoint. `serve(array $query)` is the whole HTTP request
+  in one call: it reads `lastEventId`, `limit` and `timeout` from the raw query
+  parameters, coerces and clamps them, and rejects a `lastEventId` that is
+  neither a position nor the tip sentinel with `Exception\Invalid`. `read()`,
+  `poll()` and `tip()` are there for a route that wants the pieces.
+- `Batch` — one read of a feed. Counts and iterates as its events, and carries
+  the limit it was actually built with, so `cacheControl()` cannot be handed a
+  number the read did not use: a full batch is settled history and cacheable
+  forever, anything shorter is `no-store`. `toArray()` is the wire encoding and
+  `lastId()` the position a stateless relay tracks.
+
+### Consuming
+
+- `Consumer` — the pull loop, at-least-once, with a durable position.
+  `consume(callable)` handles a batch and commits after the last event that
+  succeeded; a failing handler blocks the events behind it by design.
+- Built over a local `Readable` for a feed the same service produces, or
+  straight over a [utopia-php/client](https://github.com/utopia-php/client)
+  whose base URI points at the feed endpoint, plus the feed's name.
+- `position()`, `reset()` and `seek(eventId)` move the position by hand.
+  `seek()` is the escape hatch for a poison event: seek to the failing event's
+  own id to step past it. Both are safe to call from inside a handler.
+- `Consumer::START_TIP` starts a consumer with no stored position at the tip of
+  the feed instead of at the oldest retained event. It rides a protocol
+  extension — the `lastEventId` value `$`, which the producer resolves to its
+  newest event as the request arrives — so skipping the backlog costs no extra
+  round trip and still delivers what lands mid-poll.
+
+### Stores and cursors
+
+- `Store\Redis`, `Store\Pool` — a capped Redis stream, directly or over a
+  [pooled](https://github.com/utopia-php/pools) connection. The pooled store
+  borrows per read, so a held long poll never ties up a connection.
+- `Store\Cache` — the feed on a [Utopia cache](https://github.com/utopia-php/cache),
+  for a service that already carries one. The whole feed lives under one key,
+  so an append rewrites it (last-writer-wins — run one producing process) and
+  retention is also the cost of producing an event, which is why its default
+  `maxSize` is 1 000 rather than the 100 000 the Redis store keeps. The newest
+  id is kept under a second, tiny key so a caught-up long poll does not load
+  the feed to learn nothing.
+- `Store\Memory` — tests and single-process development. `Store\None` — no
+  backend configured; throws on use, so a misconfigured service fails loudly
+  instead of dropping events.
+- `Cursor\Cache`, `Cursor\Redis`, `Cursor\Pool`, `Cursor\Memory`, `Cursor\None`
+  — where a consumer's position lives, keyed by feed and consumer name. The
+  stored form is deliberately plain (`feed:<feed>:cursor:<consumer>` holding
+  the id as a string), so positions carry across upgrades and an operator can
+  answer "where is this consumer?" from a shell. A run's save is conditional
+  on the position it started from (read-compare-write), so an instance that
+  fell behind cannot undo newer progress, a seek, or a reset — it adopts the
+  newer position instead.
+- Retention (`maxSize`) and the long-poll read interval (`pollInterval`, in
+  milliseconds, default 500) are constructor options on every store.
+
+### The wire
+
+- A batch is the plain JSON array of CloudEvents the spec defines — no
+  envelope. An empty array means the consumer is caught up. The media type is
+  `Readable::MEDIA_TYPE`, `application/cloudevents-batch+json`, aliased as
+  `Batch::MEDIA_TYPE` for the serving side and `Remote::MEDIA_TYPE` for the
+  consuming one.
+- `Readable` is the contract both sides share — `read`, `poll`, `tip`,
+  `getName`, plus `TIP`, `MAX_BATCH` (1000) and `MAX_TIMEOUT` (30s).
+  `Appendable` is the contract of a store that owns its events;
+  `Remote` deliberately does not implement it.
+- `Remote` — another service's feed over HTTP, a `Readable` in its own right
+  rather than a store. Decoding is strict about `id`, because that is the
+  consumer's position, and tolerant of everything else, so a consumer older
+  than the producer keeps working: unknown attributes ride along as
+  extensions, and an entry that cannot be read ends the batch early rather
+  than discarding the usable events before it — unless it is the first, where
+  there is no progress to keep and the read fails loudly instead.
+- `Id` — feed positions (`{ms}-{seq}`) and the arithmetic for paging past one.
+  `Key` shapes the backend keys, escaping names so a feed and a cursor cannot
+  collide in one keyspace.
+
+### Errors
+
+Everything this library raises extends `Utopia\Feed\Exception`:
+`Exception\Invalid` for something the caller handed over, `Exception\Transport`
+for a backend or network failure, `Exception\Unsupported` for something a
+backend cannot do.