fiber_stream 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab4449558105eb57805e40970a28971e32a37e748176df0875de75816bf53d2c
-  data.tar.gz: 6d1998ce477a4602a6f23d60817f2f49b9acc6efde64b18ee90ebd7084905bd5
+  metadata.gz: c6ac2f9ec0d6888789ac2535538124b9057895b52e226d812d002e5d2955d437
+  data.tar.gz: df4722fff9e5020b24e7e23d2d4cc98ea98aa54a3f17dd86ff0825f41f007de4
 SHA512:
-  metadata.gz: 4242c44baa5c1db6f7cb6c39ac217729603838dba31876180f4fcc2382e72308cad4d5197d8687b522317dfc9ad964bcd6f85b9449f580f88324098536b8906c
-  data.tar.gz: c2cc8091ec14b27eef4a60a82c1c22503118eee9da0a1a53e24a3e137058e1dd8c5e1536e89c5ba13c7f725cdc0ad241d48ade86cbe2162f6ac5ae2d9ce8f96f
+  metadata.gz: 11389c5aaf69a315a9a932ddd06488eb7fe81b72ca265ecf2e45e7d96b4d984a67c2eee49b38dbde267ce35b4e5dfe7dff4d2e61a32330d5e09153058ad2fb22
+  data.tar.gz: e231b92f6c0ddb08aae7e0db1791b17325705705a76ace92b197d626954ae72dd1510359c5ea8f0c5cff19985f01b78cc4e62179699d244afa4d988ed4da9d51

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.2.0 - 2026-06-05
+
+### Added
+
+- `Source#zip(source)` for element-wise pairing of two sources with
+  demand-driven materialization and shortest-source completion.
+- `Source#concat(source)` for lazy source concatenation.
+- `Sink.foreach { |element| ... }` for side-effecting stream consumption
+  without accumulating elements.
+- `Flow.drop(count)` and `Source#drop(count)` for fixed-prefix dropping.
+- `Flow.take_while { |element| ... }` and `Source#take_while { |element| ... }`
+  for predicate-based prefix limiting.
+- `Flow.drop_while { |element| ... }` and
+  `Source#drop_while { |element| ... }` for predicate-based prefix dropping.
+
+### Changed
+
+- Clarified documentation around FiberStream's linear roadmap and Ractor port
+  cancellation contract.
+
 ## 0.1.0 - 2026-06-03
 
 Initial release.

data/README.md

@@ -28,16 +28,17 @@ FiberStream currently supports linear pipelines only.
 Implemented capabilities:
 
 - in-memory, IO, and backpressure-aware Ractor port sources
-- mapping, filtering, limiting, line splitting, buffering, async boundaries,
-  ordered parallel mapping, and ordered Ractor-backed mapping
-- array, first-element, fold, and IO sinks
+- lazy source concatenation and zipping
+- mapping, filtering, limiting, predicate-based limiting and dropping,
+  fixed-prefix dropping, line splitting, buffering, async boundaries, ordered
+  parallel mapping, and ordered Ractor-backed mapping
+- array, first-element, fold, foreach, and IO sinks
 - reusable flow composition and runnable pipelines
 - foreground and scheduler-backed background pipeline execution
 - public RBS signatures
 
-Not yet implemented:
-
-- graph DSLs
+FiberStream intentionally keeps the public model linear: one source, an
+ordered chain of flows, and one sink.
 
 ## Core Concepts
 
@@ -52,6 +53,30 @@ source = FiberStream::Source.each([1, 2, 3])
 source.run_with(FiberStream::Sink.to_a) # => [1, 2, 3]
 ```
 
+Sources can be concatenated without materializing the appended source until the
+first source completes:
+
+```ruby
+result =
+  FiberStream::Source.each([1, 2])
+    .concat(FiberStream::Source.each([3, 4]))
+    .run_with(FiberStream::Sink.to_a)
+
+result # => [1, 2, 3, 4]
+```
+
+Sources can also be zipped element-by-element. The zipped source emits pairs
+and completes when either input source completes:
+
+```ruby
+result =
+  FiberStream::Source.each([1, 2, 3])
+    .zip(FiberStream::Source.each(["a", "b"]))
+    .run_with(FiberStream::Sink.to_a)
+
+result # => [[1, "a"], [2, "b"]]
+```
+
 IO sources read chunks on demand and require a scheduler-backed non-blocking
 fiber:
 
@@ -107,6 +132,39 @@ FiberStream::Source.ractor_port(data_port, ack_port: ack_port)
 producer.value
 ```
 
+Streaming HTTP response bodies that implement `#each`, such as
+`async-http` response bodies, can be used with `Source.each` without buffering
+the full body first. Use the HTTP client's block form or an explicit `ensure`
+close because `Source.each` does not own the response body:
+
+```ruby
+require "async"
+require "async/http/internet/instance"
+require "fiber_stream"
+
+url = "https://raw.githubusercontent.com/elastic/examples/master/" \
+  "Common%20Data%20Formats/nginx_logs/nginx_logs"
+
+status_counts = Hash.new(0)
+
+processed =
+  Sync do
+    Async::HTTP::Internet.get(url) do |response|
+      raise "unexpected status #{response.status}" unless response.status == 200
+
+      FiberStream::Source.each(response.body)
+        .lines(max_length: 16 * 1024)
+        .map { |line| line.split.fetch(8, nil) }
+        .select { |status| status&.match?(/\A\d{3}\z/) }
+        .run_with(
+          FiberStream::Sink.foreach do |status|
+            status_counts[status] += 1
+          end
+        )
+    end
+  end
+```
+
 ### Flows
 
 Flows transform a stream lazily. Convenience methods on `Source` delegate to
@@ -136,6 +194,40 @@ FiberStream::Source.each([" a ", "", " b "])
 # => ["a", "b"]
 ```
 
+Use `ractor_map` for ordered CPU-bound mapping in Ractor workers. The mapper
+must be shareable, usually by creating it with `Ractor.shareable_proc`.
+
+```ruby
+require "digest"
+require "fiber_stream"
+
+records = [
+  { name: "alpha.bin", payload: +"A" * 200_000 },
+  { name: "bravo.bin", payload: +"B" * 120_000 }
+]
+
+HASH_RECORD =
+  Ractor.shareable_proc do |record|
+    payload = record.fetch(:payload)
+
+    {
+      name: record.fetch(:name),
+      bytes: payload.bytesize,
+      sha256: Digest::SHA256.hexdigest(payload)
+    }
+  end
+
+digests =
+  FiberStream::Source.each(records)
+    .ractor_map(workers: 2, input_transfer: :move, &HASH_RECORD)
+    .run_with(FiberStream::Sink.to_a)
+```
+
+`ractor_map` preserves input order, limits pulled-but-unemitted work to
+`workers`, and does not require `Fiber.scheduler`. Use `input_transfer: :move`
+or `output_transfer: :move` only when the moved object will not be reused by
+the sender.
+
 ### Sinks
 
 A `Sink` consumes the stream and returns a materialized value.
@@ -146,6 +238,17 @@ FiberStream::Source.each([1, 2, 3])
 # => 6
 ```
 
+Use `Sink.foreach` when the terminal operation is a side effect and the stream
+values should not be accumulated:
+
+```ruby
+count =
+  FiberStream::Source.each(["a", "b", "c"])
+    .run_with(FiberStream::Sink.foreach { |value| puts value })
+
+count # => 3
+```
+
 ### Pipelines
 
 `Source#to(sink)` creates a reusable runnable pipeline.
@@ -212,6 +315,67 @@ limited =
 limited # => [1, 2]
 ```
 
+`Flow.drop` skips a fixed prefix and then passes later elements through:
+
+```ruby
+tail =
+  FiberStream::Source.each([1, 2, 3, 4])
+    .drop(2)
+    .run_with(FiberStream::Sink.to_a)
+
+tail # => [3, 4]
+```
+
+`Flow.take_while` emits the leading prefix while a predicate is truthy, then
+closes upstream at the first false or nil result:
+
+```ruby
+prefix =
+  FiberStream::Source.each([1, 2, 3, 1])
+    .take_while { |number| number < 3 }
+    .run_with(FiberStream::Sink.to_a)
+
+prefix # => [1, 2]
+```
+
+`Flow.drop_while` skips the leading prefix while a predicate is truthy, then
+passes the first false or nil result and all later elements through:
+
+```ruby
+tail =
+  FiberStream::Source.each([1, 2, 3, 1])
+    .drop_while { |number| number < 3 }
+    .run_with(FiberStream::Sink.to_a)
+
+tail # => [3, 1]
+```
+
+`Source#concat` preserves pull-driven demand across source boundaries. The
+appended source is not materialized while the first source can still satisfy
+downstream demand:
+
+```ruby
+first =
+  FiberStream::Source.each([1])
+    .concat(FiberStream::Source.each([2]))
+    .run_with(FiberStream::Sink.first)
+
+first # => 1
+```
+
+`Source#zip` keeps input source materialization behind downstream demand. The
+other source is not materialized until the receiver has produced an element for
+a pair:
+
+```ruby
+first =
+  FiberStream::Source.each([1])
+    .zip(FiberStream::Source.each([2]))
+    .run_with(FiberStream::Sink.first)
+
+first # => [1, 2]
+```
+
 `Flow.buffer(count)` allows bounded prefetch. `Flow.async`, `Flow.buffer`,
 `Flow.parallel_map`, `Source.io`, `Sink.io`, and `Pipeline#run_async` require an
 installed `Fiber.scheduler` and a non-blocking current fiber when demanded or
@@ -229,11 +393,16 @@ Sources:
 Source convenience methods:
 
 - `Source#via(flow)`
+- `Source#concat(source)`
+- `Source#zip(source)`
 - `Source#map { |element| ... }`
 - `Source#parallel_map(concurrency:) { |element| ... }`
 - `Source#ractor_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
 - `Source#select { |element| ... }`
 - `Source#take(count)`
+- `Source#drop(count)`
+- `Source#take_while { |element| ... }`
+- `Source#drop_while { |element| ... }`
 - `Source#async`
 - `Source#buffer(count)`
 - `Source#lines(chomp: true, max_length: nil)`
@@ -247,6 +416,9 @@ Flows:
 - `FiberStream::Flow.ractor_map(workers:, input_transfer: :copy, output_transfer: :copy) { |element| ... }`
 - `FiberStream::Flow.select { |element| ... }`
 - `FiberStream::Flow.take(count)`
+- `FiberStream::Flow.drop(count)`
+- `FiberStream::Flow.take_while { |element| ... }`
+- `FiberStream::Flow.drop_while { |element| ... }`
 - `FiberStream::Flow.async`
 - `FiberStream::Flow.buffer(count)`
 - `FiberStream::Flow.lines(chomp: true, max_length: nil)`
@@ -258,6 +430,7 @@ Sinks:
 - `FiberStream::Sink.to_a`
 - `FiberStream::Sink.first`
 - `FiberStream::Sink.fold(initial) { |accumulator, element| ... }`
+- `FiberStream::Sink.foreach { |element| ... }`
 - `FiberStream::Sink.io(io, close: false, flush: false)`
 
 Pipelines:
@@ -283,6 +456,7 @@ bundle exec ruby examples/background_execution.rb
 bundle exec ruby examples/ractor_map_hashing.rb
 bundle exec ruby examples/ractor_port_source.rb
 bundle exec ruby examples/async_http_requests.rb
+bundle exec ruby examples/async_http_streaming_body.rb
 ```
 
 `examples/backpressure_buffer.rb` prints timestamped producer and consumer
@@ -297,6 +471,10 @@ with a shareable mapper proc and `input_transfer: :move`.
 `examples/async_http_requests.rb` starts a local HTTP server and shows
 FiberStream overlapping independent HTTP request waits with `parallel_map`.
 
+`examples/async_http_streaming_body.rb` streams a public nginx access log with
+`async-http`, feeds the response body through `Source.each(response.body)`, and
+aggregates lines without storing the full body.
+
 Benchmark scripts live under `benchmarks/`.
 
 ```sh

data/examples/README.md

@@ -12,6 +12,7 @@ bundle exec ruby examples/background_execution.rb
 bundle exec ruby examples/ractor_map_hashing.rb
 bundle exec ruby examples/ractor_port_source.rb
 bundle exec ruby examples/async_http_requests.rb
+bundle exec ruby examples/async_http_streaming_body.rb
 ```
 
 `basic_pipeline.rb` uses only in-memory values and does not require an async
@@ -49,3 +50,7 @@ demand.
 `async_http_requests.rb` starts a local HTTP server and compares serial
 requests with FiberStream `parallel_map` requests. It keeps responses ordered
 while overlapping independent network waits.
+
+`async_http_streaming_body.rb` downloads a public nginx access log with
+`async-http` and streams `response.body` through `Source.each`, `Flow.lines`,
+and `Sink.foreach` so the full HTTP body is not buffered in memory.

data/examples/async_http_streaming_body.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../lib", __dir__))
+
+require "async"
+require "async/http/internet/instance"
+require "fiber_stream"
+
+DEFAULT_URL =
+  "https://raw.githubusercontent.com/elastic/examples/master/" \
+  "Common%20Data%20Formats/nginx_logs/nginx_logs"
+
+URL = ENV.fetch("FIBER_STREAM_HTTP_LOG_URL", DEFAULT_URL)
+PROGRESS_EVERY = Integer(ENV.fetch("FIBER_STREAM_HTTP_PROGRESS_EVERY", "10_000"))
+
+LOG_LINE =
+  /
+    \A
+    (?<remote_addr>\S+)\s+\S+\s+\S+\s+
+    \[[^\]]+\]\s+
+    "[^"]+"\s+
+    (?<status>\d{3})\s+
+    (?<bytes>\d+|-)\s
+  /x
+
+def monotonic_time
+  Process.clock_gettime(Process::CLOCK_MONOTONIC)
+end
+
+def parse_access_log(line)
+  match = LOG_LINE.match(line)
+  return nil unless match
+
+  {
+    remote_addr: match[:remote_addr],
+    status: match[:status],
+    bytes: match[:bytes] == "-" ? 0 : match[:bytes].to_i
+  }
+end
+
+def empty_stats
+  {
+    lines: 0,
+    parsed: 0,
+    payload_bytes: 0,
+    statuses: Hash.new(0),
+    remote_addrs: Hash.new(0),
+    started_at: monotonic_time
+  }
+end
+
+def record_entry(stats, entry)
+  stats[:lines] += 1
+
+  if entry
+    stats[:parsed] += 1
+    stats[:payload_bytes] += entry.fetch(:bytes)
+    stats[:statuses][entry.fetch(:status)] += 1
+    stats[:remote_addrs][entry.fetch(:remote_addr)] += 1
+  end
+
+  if (stats[:lines] % PROGRESS_EVERY).zero?
+    elapsed = monotonic_time - stats.fetch(:started_at)
+    puts format(
+      "processed %<lines>d lines in %<elapsed>.2fs",
+      lines: stats.fetch(:lines),
+      elapsed: elapsed
+    )
+  end
+
+  stats
+end
+
+def print_summary(stats)
+  elapsed = monotonic_time - stats.fetch(:started_at)
+  mib = stats.fetch(:payload_bytes).fdiv(1024 * 1024)
+
+  puts
+  puts "Streaming HTTP body summary"
+  puts "URL: #{URL}"
+  puts format("lines parsed: %<parsed>d/%<lines>d", stats)
+  puts format("logged payload bytes: %<mib>.2f MiB", mib: mib)
+  puts format("unique remote addresses: %<count>d", count: stats.fetch(:remote_addrs).length)
+  puts format("elapsed: %<elapsed>.2fs", elapsed: elapsed)
+
+  puts
+  puts "HTTP status counts"
+  stats.fetch(:statuses).sort.each do |status, count|
+    puts format("- %<status>s: %<count>d", status: status, count: count)
+  end
+end
+
+stats = empty_stats
+
+processed =
+  Sync do
+    Async::HTTP::Internet.get(URL) do |response|
+      unless response.status == 200
+        raise "unexpected HTTP status #{response.status} for #{URL}"
+      end
+
+      FiberStream::Source.each(response.body)
+        .lines(max_length: 16 * 1024)
+        .map { |line| parse_access_log(line) }
+        .run_with(
+          FiberStream::Sink.foreach do |entry|
+            record_entry(stats, entry)
+          end
+        )
+    end
+  end
+
+raise "processed count mismatch" unless processed == stats.fetch(:lines)
+
+print_summary(stats)

data/lib/fiber_stream/flow.rb

@@ -75,6 +75,43 @@ module FiberStream
       new { |upstream| Pull.take(upstream, count) }
     end
 
+    # Creates a fixed-prefix dropping flow.
+    #
+    # The flow discards the first `count` upstream elements, then passes later
+    # elements through unchanged. `drop(0)` behaves as pass-through. Negative
+    # counts raise `ArgumentError`; non-Integer counts raise `TypeError`.
+    def self.drop(count)
+      raise TypeError, "count must be an Integer" unless count.is_a?(Integer)
+      raise ArgumentError, "count must be non-negative" if count.negative?
+
+      new { |upstream| Pull.drop(upstream, count) }
+    end
+
+    # Creates a predicate-based limiting flow.
+    #
+    # The flow emits leading elements while the block result is truthy. The
+    # first false or nil result completes the stream without emitting that
+    # element and closes upstream during the same downstream pull. Exceptions
+    # raised by the block fail the stream and are re-raised from
+    # `Source#run_with`.
+    def self.take_while(&block)
+      raise ArgumentError, "missing block" unless block
+
+      new { |upstream| Pull.take_while(upstream, block) }
+    end
+
+    # Creates a predicate-based prefix-dropping flow.
+    #
+    # The flow drops leading elements while the block result is truthy. The
+    # first false or nil result, and all later elements, pass through unchanged.
+    # After that boundary the block is not called again. Exceptions raised by
+    # the block fail the stream and are re-raised from `Source#run_with`.
+    def self.drop_while(&block)
+      raise ArgumentError, "missing block" unless block
+
+      new { |upstream| Pull.drop_while(upstream, block) }
+    end
+
     # Creates a scheduler-backed asynchronous boundary.
     #
     # The boundary starts its producer on the first downstream demand and

data/lib/fiber_stream/pull/concat.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module FiberStream
+  module Pull
+    # Pull stream that emits all values from one materialized source, then all
+    # values from a second source materialized only after the first completes.
+    class Concat
+      def initialize(left_materializer, right_materializer)
+        @left_materializer = left_materializer
+        @right_materializer = right_materializer
+        @left = @left_materializer.call
+        @right = nil
+        @phase = :left
+        @closed = false
+        @done = false
+      end
+
+      def next
+        return DONE if @closed || @done
+
+        case @phase
+        when :left
+          next_left
+        when :right
+          next_right
+        else
+          DONE
+        end
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        close_materialized_streams
+      end
+
+      private
+
+      def next_left
+        value = @left.next
+        return value unless Pull.done?(value)
+
+        close_left
+        @phase = :right
+        @right = @right_materializer.call
+        next_right
+      end
+
+      def next_right
+        value = @right.next
+        return value unless Pull.done?(value)
+
+        close_right
+        @done = true
+        DONE
+      end
+
+      def close_left
+        stream = @left
+        return unless stream
+
+        stream.close
+        @left = nil
+      end
+
+      def close_right
+        stream = @right
+        return unless stream
+
+        stream.close
+        @right = nil
+      end
+
+      def close_materialized_streams
+        first_error = nil
+
+        [@right, @left].each do |stream|
+          next unless stream
+
+          begin
+            stream.close
+          rescue StandardError => error
+            first_error ||= error
+          end
+        end
+
+        @right = nil
+        @left = nil
+
+        raise first_error if first_error
+      end
+    end
+  end
+end

data/lib/fiber_stream/pull/drop.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module FiberStream
+  module Pull
+    # Fixed-prefix dropping stage.
+    #
+    # It discards the first `count` upstream elements on downstream demand, then
+    # passes later elements through without buffering.
+    class Drop
+      def initialize(upstream, count)
+        @upstream = upstream
+        @remaining = count
+        @closed = false
+        @done = false
+      end
+
+      def next
+        return DONE if @closed || @done
+
+        drop_prefix
+        return DONE if @done
+
+        pull_retained_value
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        @upstream.close
+      end
+
+      private
+
+      def drop_prefix
+        while @remaining.positive?
+          value = @upstream.next
+          if Pull.done?(value)
+            @done = true
+            return
+          end
+
+          @remaining -= 1
+        end
+      end
+
+      def pull_retained_value
+        value = @upstream.next
+        if Pull.done?(value)
+          @done = true
+          return DONE
+        end
+
+        value
+      end
+    end
+  end
+end

data/lib/fiber_stream/pull/drop_while.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module FiberStream
+  module Pull
+    # Predicate-based prefix dropping stage.
+    #
+    # It drops leading elements while the predicate is truthy. The first falsey
+    # element and all later elements pass through unchanged.
+    class DropWhile
+      def initialize(upstream, predicate)
+        @upstream = upstream
+        @predicate = predicate
+        @dropping = true
+        @closed = false
+        @done = false
+      end
+
+      def next
+        return DONE if @closed || @done
+
+        return pull_pass_through unless @dropping
+
+        pull_until_retained
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        @upstream.close
+      end
+
+      private
+
+      def pull_until_retained
+        loop do
+          value = @upstream.next
+          if Pull.done?(value)
+            @done = true
+            return DONE
+          end
+
+          next if @predicate.call(value)
+
+          @dropping = false
+          return value
+        end
+      end
+
+      def pull_pass_through
+        value = @upstream.next
+        if Pull.done?(value)
+          @done = true
+          return DONE
+        end
+
+        value
+      end
+    end
+  end
+end

data/lib/fiber_stream/pull/take_while.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module FiberStream
+  module Pull
+    # Predicate-based limiting stage.
+    #
+    # It forwards the leading prefix whose predicate results are truthy. The
+    # first falsey predicate result is consumed, not emitted, and closes
+    # upstream immediately.
+    class TakeWhile
+      def initialize(upstream, predicate)
+        @upstream = upstream
+        @predicate = predicate
+        @closed = false
+        @done = false
+      end
+
+      def next
+        return DONE if @closed || @done
+
+        value = @upstream.next
+        if Pull.done?(value)
+          @done = true
+          return DONE
+        end
+
+        return value if @predicate.call(value)
+
+        @done = true
+        close
+        DONE
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        @upstream.close
+      end
+    end
+  end
+end

data/lib/fiber_stream/pull/zip.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module FiberStream
+  module Pull
+    # Pull stream that emits pairs from two source definitions.
+    #
+    # The receiver side is materialized on first downstream demand. The other
+    # side is materialized only after the receiver produces a value for a pair.
+    class Zip
+      def initialize(left_materializer, right_materializer)
+        @left_materializer = left_materializer
+        @right_materializer = right_materializer
+        @left = nil
+        @right = nil
+        @closed = false
+        @done = false
+      end
+
+      def next
+        return DONE if @closed || @done
+
+        left = materialize_left
+        left_value = left.next
+        if Pull.done?(left_value)
+          @done = true
+          close_materialized_streams
+          return DONE
+        end
+
+        right = materialize_right
+        right_value = right.next
+        if Pull.done?(right_value)
+          @done = true
+          close_materialized_streams
+          return DONE
+        end
+
+        [left_value, right_value]
+      rescue StandardError
+        @done = true
+        close_materialized_streams(raise_error: false)
+        raise
+      end
+
+      def close
+        return if @closed
+
+        @closed = true
+        close_materialized_streams
+      end
+
+      private
+
+      def materialize_left
+        @left ||= @left_materializer.call
+      end
+
+      def materialize_right
+        @right ||= @right_materializer.call
+      end
+
+      def close_materialized_streams(raise_error: true)
+        streams = [@left, @right]
+        @left = nil
+        @right = nil
+
+        first_error = nil
+
+        streams.each do |stream|
+          next unless stream
+
+          begin
+            stream.close
+          rescue StandardError => error
+            first_error ||= error
+          end
+        end
+
+        raise first_error if raise_error && first_error
+      end
+    end
+  end
+end

data/lib/fiber_stream/pull.rb

@@ -28,6 +28,14 @@ module FiberStream
       RactorPortSource.new(port, ack_port, ack_transfer, cancel)
     end
 
+    def self.concat(left_materializer, right_materializer)
+      Concat.new(left_materializer, right_materializer)
+    end
+
+    def self.zip(left_materializer, right_materializer)
+      Zip.new(left_materializer, right_materializer)
+    end
+
     def self.map(upstream, transform)
       Map.new(upstream, transform)
     end
@@ -48,6 +56,18 @@ module FiberStream
       Take.new(upstream, count)
     end
 
+    def self.drop(upstream, count)
+      Drop.new(upstream, count)
+    end
+
+    def self.take_while(upstream, predicate)
+      TakeWhile.new(upstream, predicate)
+    end
+
+    def self.drop_while(upstream, predicate)
+      DropWhile.new(upstream, predicate)
+    end
+
     def self.async(upstream)
       AsyncBoundary.new(upstream)
     end
@@ -67,9 +87,14 @@ end
 require_relative "pull/each"
 require_relative "pull/io_source"
 require_relative "pull/ractor_port_source"
+require_relative "pull/concat"
+require_relative "pull/zip"
 require_relative "pull/map"
 require_relative "pull/select"
 require_relative "pull/take"
+require_relative "pull/drop"
+require_relative "pull/take_while"
+require_relative "pull/drop_while"
 require_relative "pull/lines"
 require_relative "pull/async_boundary"
 require_relative "pull/buffer_boundary"
@@ -78,8 +103,8 @@ require_relative "pull/ractor_map_boundary"
 
 module FiberStream
   module Pull
-    private_constant :Each, :IOSource, :RactorPortSource, :Map, :Select, :Take, :Lines,
-                     :AsyncBoundary, :BufferBoundary, :ParallelMapBoundary,
-                     :RactorMapBoundary
+    private_constant :Each, :IOSource, :RactorPortSource, :Concat, :Zip, :Map, :Select, :Take, :Drop,
+                     :TakeWhile, :DropWhile, :Lines, :AsyncBoundary, :BufferBoundary,
+                     :ParallelMapBoundary, :RactorMapBoundary
   end
 end

data/lib/fiber_stream/sink.rb

@@ -56,6 +56,30 @@ module FiberStream
       end
     end
 
+    # Creates a sink that runs a block for each stream element.
+    #
+    # The sink consumes upstream until normal completion, calls the block once
+    # per element in input order, and returns the number of elements whose block
+    # completed successfully. Exceptions raised by the block fail the stream and
+    # are re-raised from `Source#run_with`.
+    def self.foreach(&block)
+      raise ArgumentError, "missing block" unless block
+
+      new do |stream|
+        count = 0
+
+        loop do
+          value = stream.next
+          break if Pull.done?(value)
+
+          block.call(value)
+          count += 1
+        end
+
+        count
+      end
+    end
+
     # Creates a sink that writes String chunks to an IO-like object.
     #
     # The sink consumes upstream until normal completion and returns the number

data/lib/fiber_stream/source.rb

@@ -62,6 +62,37 @@ module FiberStream
       self.class.__send__(:new, @source_factory, @flows + [flow])
     end
 
+    # Returns a new source definition that emits this source, then `source`.
+    #
+    # Construction is lazy. The appended source is not materialized or pulled
+    # until downstream demand observes completion from this source. Flows
+    # attached before concat stay scoped to their source; flows attached after
+    # concat apply to the combined output.
+    def concat(source)
+      raise TypeError, "expected FiberStream::Source" unless source.is_a?(Source)
+
+      self.class.__send__(
+        :new,
+        -> { Pull.concat(materializer, source.__send__(:materializer)) }
+      )
+    end
+
+    # Returns a new source definition that emits pairs from this source and
+    # `source`.
+    #
+    # Construction is lazy. The receiver side is materialized only when
+    # downstream demand reaches the zip stage; the other side is materialized
+    # only after the receiver produces an element for a pair. The zipped source
+    # completes when either input completes.
+    def zip(source)
+      raise TypeError, "expected FiberStream::Source" unless source.is_a?(Source)
+
+      self.class.__send__(
+        :new,
+        -> { Pull.zip(materializer, source.__send__(:materializer)) }
+      )
+    end
+
     # Returns a new source definition that maps each element with `block`.
     #
     # This is a convenience wrapper around `via(FiberStream::Flow.map { ... })`
@@ -115,6 +146,34 @@ module FiberStream
       via(Flow.take(count))
     end
 
+    # Returns a new source definition that drops the first `count` elements.
+    #
+    # This is a convenience wrapper around `via(FiberStream::Flow.drop(count))`
+    # and preserves the same validation and pull-driven backpressure behavior.
+    def drop(count)
+      via(Flow.drop(count))
+    end
+
+    # Returns a new source definition that emits leading elements while `block`
+    # is truthy.
+    #
+    # This is a convenience wrapper around
+    # `via(FiberStream::Flow.take_while { ... })` and preserves the same
+    # predicate truthiness, early completion, and upstream close behavior.
+    def take_while(&block)
+      via(Flow.take_while(&block))
+    end
+
+    # Returns a new source definition that drops leading elements while `block`
+    # is truthy.
+    #
+    # This is a convenience wrapper around
+    # `via(FiberStream::Flow.drop_while { ... })` and preserves the same
+    # predicate truthiness, prefix-dropping, and pass-through behavior.
+    def drop_while(&block)
+      via(Flow.drop_while(&block))
+    end
+
     # Returns a new source definition with an asynchronous boundary.
     #
     # This is a convenience wrapper around `via(FiberStream::Flow.async)` and
@@ -161,10 +220,7 @@ module FiberStream
       primary_error = nil
 
       begin
-        stream = @source_factory.call
-        @flows.each do |flow|
-          stream = flow.__send__(:attach, stream)
-        end
+        stream = materialize
 
         sink.__send__(:run, stream)
       rescue StandardError => error
@@ -180,5 +236,30 @@ module FiberStream
     end
 
     private_class_method :new
+
+    private
+
+    def materializer
+      -> { materialize }
+    end
+
+    def materialize
+      stream = nil
+
+      begin
+        stream = @source_factory.call
+        @flows.each do |flow|
+          stream = flow.__send__(:attach, stream)
+        end
+        stream
+      rescue StandardError
+        begin
+          stream&.close
+        rescue StandardError
+          nil
+        end
+        raise
+      end
+    end
   end
 end

data/lib/fiber_stream/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module FiberStream
-  VERSION = "0.1.0"
+  VERSION = "0.2.0"
 end

data/sig/fiber_stream.rbs

@@ -2,6 +2,7 @@ module FiberStream
   type ractor_transfer_policy = :copy | :move
   type ractor_map_error_kind = :input_transfer | :output_transfer | :worker | :worker_termination | :isolation
   type ractor_port_source_error_kind = :invalid_message | :producer_failure | :receive | :ack_transfer | :cancel_transfer
+  type ractor_port_cancel_reason = :closed
 
   class SchedulerRequiredError < RuntimeError
   end
@@ -42,7 +43,7 @@ module FiberStream
     end
 
     class Cancel < Data
-      attr_reader reason: Symbol
+      attr_reader reason: ractor_port_cancel_reason
     end
   end
 
@@ -51,11 +52,16 @@ module FiberStream
     def self.io: (untyped io, ?chunk_size: Integer, ?close: bool) -> Source[String]
     def self.ractor_port: [Elem] (untyped port, ack_port: untyped, ?ack_transfer: ractor_transfer_policy, ?cancel: bool) -> Source[Elem]
     def via: [Out] (Flow[Elem, Out] flow) -> Source[Out]
+    def concat: [Other] (Source[Other] source) -> Source[Elem | Other]
+    def zip: [Other] (Source[Other] source) -> Source[[Elem, Other]]
     def map: [Out] () { (Elem) -> Out } -> Source[Out]
     def parallel_map: [Out] (concurrency: Integer) { (Elem) -> Out } -> Source[Out]
     def ractor_map: [Out] (workers: Integer, ?input_transfer: ractor_transfer_policy, ?output_transfer: ractor_transfer_policy) { (Elem) -> Out } -> Source[Out]
     def select: () { (Elem) -> boolish } -> Source[Elem]
     def take: (Integer count) -> Source[Elem]
+    def drop: (Integer count) -> Source[Elem]
+    def take_while: () { (Elem) -> boolish } -> Source[Elem]
+    def drop_while: () { (Elem) -> boolish } -> Source[Elem]
     def async: () -> Source[Elem]
     def buffer: (Integer count) -> Source[Elem]
     def lines: (?chomp: bool, ?max_length: Integer?) -> Source[String]
@@ -69,6 +75,9 @@ module FiberStream
     def self.ractor_map: [In, Out] (workers: Integer, ?input_transfer: ractor_transfer_policy, ?output_transfer: ractor_transfer_policy) { (In) -> Out } -> Flow[In, Out]
     def self.select: [Elem] () { (Elem) -> boolish } -> Flow[Elem, Elem]
     def self.take: [Elem] (Integer count) -> Flow[Elem, Elem]
+    def self.drop: [Elem] (Integer count) -> Flow[Elem, Elem]
+    def self.take_while: [Elem] () { (Elem) -> boolish } -> Flow[Elem, Elem]
+    def self.drop_while: [Elem] () { (Elem) -> boolish } -> Flow[Elem, Elem]
     def self.async: [Elem] () -> Flow[Elem, Elem]
     def self.buffer: [Elem] (Integer count) -> Flow[Elem, Elem]
     def self.lines: (?chomp: bool, ?max_length: Integer?) -> Flow[String, String]
@@ -80,6 +89,7 @@ module FiberStream
     def self.to_a: [Elem] () -> Sink[Elem, Array[Elem]]
     def self.first: [Elem] () -> Sink[Elem, Elem?]
     def self.fold: [Elem, Acc] (Acc initial) { (Acc, Elem) -> Acc } -> Sink[Elem, Acc]
+    def self.foreach: [Elem] () { (Elem) -> void } -> Sink[Elem, Integer]
     def self.io: (untyped io, ?close: bool, ?flush: bool) -> Sink[String, Integer]
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: fiber_stream
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Dai Akatsuka
@@ -23,6 +23,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: async-http
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.95'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0.95'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
@@ -95,6 +109,7 @@ files:
 - README.md
 - examples/README.md
 - examples/async_http_requests.rb
+- examples/async_http_streaming_body.rb
 - examples/background_execution.rb
 - examples/backpressure_buffer.rb
 - examples/basic_pipeline.rb
@@ -110,6 +125,9 @@ files:
 - lib/fiber_stream/pull.rb
 - lib/fiber_stream/pull/async_boundary.rb
 - lib/fiber_stream/pull/buffer_boundary.rb
+- lib/fiber_stream/pull/concat.rb
+- lib/fiber_stream/pull/drop.rb
+- lib/fiber_stream/pull/drop_while.rb
 - lib/fiber_stream/pull/each.rb
 - lib/fiber_stream/pull/io_source.rb
 - lib/fiber_stream/pull/lines.rb
@@ -119,6 +137,8 @@ files:
 - lib/fiber_stream/pull/ractor_port_source.rb
 - lib/fiber_stream/pull/select.rb
 - lib/fiber_stream/pull/take.rb
+- lib/fiber_stream/pull/take_while.rb
+- lib/fiber_stream/pull/zip.rb
 - lib/fiber_stream/ractor_port.rb
 - lib/fiber_stream/running_pipeline.rb
 - lib/fiber_stream/sink.rb
@@ -131,7 +151,7 @@ licenses:
 metadata:
   allowed_push_host: https://rubygems.org
   homepage_uri: https://github.com/dakatsuka/fiber_stream
-  source_code_uri: https://github.com/dakatsuka/fiber_stream/tree/v0.1.0
+  source_code_uri: https://github.com/dakatsuka/fiber_stream/tree/v0.2.0
   changelog_uri: https://github.com/dakatsuka/fiber_stream/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []