laravel-cloud-rails 0.1.1

data/lib/action_cable/subscription_adapter/cloud/transport.js

@@ -0,0 +1,167 @@
+(() => {
+    if (globalThis.WebSocket.__laravelCloudBridge) return;
+    const config = globalThis.__laravelCloudWebsockets;
+    const NativeWebSocket = globalThis.WebSocket;
+    const endpoint = '/__laravel_cloud/cable';
+    const protocol = 'actioncable-v1-json';
+
+    class CableSocket extends EventTarget {
+        constructor(url) {
+            super();
+            this.url = new URL(url, location.href).href;
+            this.protocol = protocol;
+            this.extensions = '';
+            this.readyState = 0;
+            this.bufferedAmount = 0;
+            this.binaryType = 'blob';
+            this.sequence = 0;
+            this.joined = new Map();
+            this.queue = Promise.resolve();
+            this.abort = new AbortController();
+            this.onPageHide = () => this.close();
+            globalThis.addEventListener("pagehide", this.onPageHide, { once: true });
+            this.transport = new NativeWebSocket(
+                `${config.scheme === 'https' ? 'wss' : 'ws'}://${config.host}:${config.port}/app/${encodeURIComponent(config.key)}?protocol=7&client=laravel-cloud-rails&version=1`
+            );
+            this.transport.addEventListener('message', event => {
+                try {
+                    this.receive(JSON.parse(event.data)).catch(error => this.fail(error));
+                } catch (error) {
+                    this.fail(error);
+                }
+            });
+            this.transport.addEventListener('close', event => this.finish(event.code, event.reason, event.wasClean));
+            this.transport.addEventListener('error', () => this.fail(new Error('WebSocket backend unavailable')));
+            this.deadline = setTimeout(() => this.fail(new Error('Connection timed out')), 12000);
+        }
+
+        async request(command, keepalive = false) {
+            const response = await fetch(endpoint, {
+                method: 'POST',
+                credentials: 'same-origin',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ ...command, token: this.token, request_id: crypto.randomUUID() }),
+                cache: 'no-store',
+                keepalive,
+                signal: keepalive ? AbortSignal.timeout(5000) : AbortSignal.any([this.abort.signal, AbortSignal.timeout(10000)]),
+            });
+            const result = await response.json();
+            if (!response.ok) {
+                const error = new Error(result.error || `Channel request failed: HTTP ${response.status}`);
+                error.terminal = [400, 401, 403, 404, 413, 415].includes(response.status);
+                throw error;
+            }
+            return result;
+        }
+
+        async receive(event) {
+            const data = typeof event.data === 'string' ? JSON.parse(event.data) : event.data;
+            if (event.event === 'pusher:connection_established') {
+                const url = new URL(this.url);
+                const result = await this.request({ command: 'connect', socket_id: data.socket_id, url: url.pathname + url.search });
+                this.token = result.token;
+                if (this.readyState > 1) {
+                    this.release();
+                    return;
+                }
+                const pending = result.channels.map(channel => new Promise(resolve => {
+                    this.joined.set(channel.name, resolve);
+                    this.transport.send(JSON.stringify({ event: 'pusher:subscribe', data: { channel: channel.name, auth: channel.auth } }));
+                }));
+                await Promise.all(pending);
+                if (this.readyState > 1) return;
+                clearTimeout(this.deadline);
+                this.readyState = 1;
+                this.emit(new Event('open'));
+                await this.request({ command: 'ready' });
+                this.lease = setInterval(() => this.send(JSON.stringify({ command: 'lease' })), 30000);
+                return;
+            }
+            if (event.event === 'pusher_internal:subscription_succeeded') {
+                this.joined.get(event.channel)?.();
+                return;
+            }
+            if (event.event === 'pusher:ping') {
+                this.transport.send(JSON.stringify({ event: 'pusher:pong', data: {} }));
+                return;
+            }
+            if (event.event === 'pusher:error' || event.event === 'pusher:subscription_error') {
+                throw new Error('WebSocket subscription failed');
+            }
+            if (event.event === 'cloud-heartbeat' && this.readyState === 1) {
+                this.message({ type: 'ping', message: data.time });
+            }
+            if (event.event === 'cloud-frame' && this.readyState === 1) {
+                if (data.sequence <= this.sequence) return;
+                if (data.sequence !== this.sequence + 1) throw new Error('Connection stream interrupted');
+                this.sequence = data.sequence;
+                this.message(data.frame);
+            }
+        }
+
+        send(raw) {
+            if (this.readyState !== 1) throw new DOMException('WebSocket is not open', 'InvalidStateError');
+            const command = JSON.parse(raw);
+            this.queue = this.queue.then(() => this.request(command)).catch(error => this.fail(error));
+        }
+
+        message(frame) {
+            this.emit(new MessageEvent('message', { data: JSON.stringify(frame) }));
+        }
+
+        emit(event) {
+            this[`on${event.type}`]?.(event);
+            this.dispatchEvent(event);
+        }
+
+        fail(error) {
+            if (this.readyState > 1) return;
+            this.emit(new Event('error'));
+            // Like Rails' own rejection: stops the client's reconnect loop, even before open.
+            if (error.terminal) this.message({ type: 'disconnect', reason: error.message, reconnect: false });
+            this.finish(error.terminal ? 1008 : 1006, error.message, false);
+            this.transport.close();
+        }
+
+        // A keepalive request survives page unload. sendBeacon can't be used:
+        // Chrome refuses beacons with a JSON content type.
+        release() {
+            if (this.token) this.request({ command: 'disconnect' }, true).catch(() => {});
+        }
+
+        close(code = 1000, reason = '') {
+            if (this.readyState > 1) return;
+            this.readyState = 2;
+            this.release();
+            this.transport.close();
+            this.finish(code, reason, true);
+        }
+
+        finish(code = 1006, reason = '', wasClean = false) {
+            if (this.readyState === 3) return;
+            if (this.readyState < 2) this.release();
+            this.readyState = 3;
+            clearTimeout(this.deadline);
+            clearInterval(this.lease);
+            globalThis.removeEventListener("pagehide", this.onPageHide);
+            this.abort.abort();
+            this.emit(new CloseEvent('close', { code, reason, wasClean }));
+        }
+    }
+
+    function CloudWebSocket(url, protocols = []) {
+        if (!new.target) throw new TypeError('WebSocket constructor requires new');
+        const names = Array.isArray(protocols) ? protocols : [protocols];
+        if (names.includes(protocol)) return new CableSocket(url);
+        return new NativeWebSocket(url, protocols);
+    }
+
+    for (const [name, value] of Object.entries({ CONNECTING: 0, OPEN: 1, CLOSING: 2, CLOSED: 3 })) {
+        Object.defineProperty(CloudWebSocket, name, { value, enumerable: true });
+        Object.defineProperty(CableSocket.prototype, name, { value });
+    }
+    Object.defineProperty(CloudWebSocket, Symbol.hasInstance, { value: value => value instanceof NativeWebSocket || value instanceof CableSocket });
+    CloudWebSocket.__laravelCloudBridge = true;
+    CloudWebSocket.prototype = NativeWebSocket.prototype;
+    globalThis.WebSocket = CloudWebSocket;
+})();

data/lib/action_cable/subscription_adapter/cloud.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require "action_cable"
+require "action_cable/subscription_adapter/base"
+require "action_cable/subscription_adapter/channel_prefix"
+require "securerandom"
+require "erb"
+require_relative "../../laravel_cloud/websockets"
+
+module ActionCable
+  module SubscriptionAdapter
+    # `adapter: cloud` in config/cable.yml. Browsers hold their socket to Cloud
+    # WebSockets; channel commands reach Rails over same-origin HTTP
+    # (Middleware) and run against a virtual Action Cable connection
+    # (Session), whose frames go back through Cloud WebSockets.
+    #
+    # Broadcasting only publishes over HTTP, so processes that never subscribe
+    # (jobs, consoles) don't open a connection.
+    class Cloud < Base
+      prepend ChannelPrefix
+
+      Websockets = ::LaravelCloud::Websockets
+
+      # A malformed command from the browser transport.
+      class InvalidCommand < Websockets::Error; end
+
+      def self.stream_channel(stream)
+        "private-roc-stream-#{Digest::SHA256.hexdigest(stream)}"
+      end
+
+      # The owner cookie binds connection tokens to the browser that opened them.
+      def self.owner(request)
+        value = Rack::Utils.parse_cookies_header(request.get_header("HTTP_COOKIE").to_s)["__laravel_cloud_owner"]
+        return unless value.is_a?(String) && value.ascii_only? && value.match?(/\A[0-9a-f]{48}\.[0-9a-f]{64}\z/)
+        nonce, signature = value.split(".")
+        nonce if ActiveSupport::SecurityUtils.secure_compare(Websockets.sign("roc-owner:#{nonce}"), signature)
+      end
+
+      def self.owner_cookie
+        nonce = SecureRandom.hex(24)
+        "#{nonce}.#{Websockets.sign("roc-owner:#{nonce}")}"
+      end
+
+      def self.runtime
+        @runtime_lock ||= Mutex.new
+        @runtime_lock.synchronize do
+          if !@runtime || @runtime.pid != Process.pid || !@runtime.alive?
+            @runtime = Runtime.new
+          end
+          @runtime
+        end
+      end
+
+      def initialize(server)
+        Websockets.settings
+        super
+        @bindings = {}
+        @bindings_lock = Mutex.new
+      end
+
+      def broadcast(channel, payload)
+        Websockets.publish(self.class.stream_channel(channel), "cloud-broadcast", payload)
+      end
+
+      def subscribe(channel, callback, success_callback = nil)
+        runtime = self.class.runtime
+        @bindings_lock.synchronize { @bindings[[channel, callback]] = runtime }
+        runtime.subscribe(channel, callback, success_callback)
+      end
+
+      def unsubscribe(channel, callback)
+        runtime = @bindings_lock.synchronize { @bindings.delete([channel, callback]) }
+        runtime&.unsubscribe(channel, callback)
+      end
+
+      def shutdown
+        runtimes = @bindings_lock.synchronize { @bindings.values.uniq }
+        runtimes.each(&:stop)
+      end
+    end
+  end
+end
+
+require_relative "cloud/runtime"
+require_relative "cloud/middleware"
+require_relative "cloud/railtie" if defined?(Rails::Railtie)

data/lib/active_job/queue_adapters/cloud_adapter.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module ActiveJob
+  module QueueAdapters
+    # `config.active_job.queue_adapter = :cloud`. SQS has no priority, so
+    # `priority` is ignored.
+    class CloudAdapter < (defined?(AbstractAdapter) ? AbstractAdapter : Object)
+      def initialize(runtime: nil)
+        super()
+        @runtime = runtime
+      end
+
+      def enqueue(job)
+        dispatcher.dispatch(job, delay: 0)
+      end
+
+      def enqueue_at(job, timestamp)
+        dispatcher.dispatch(job, delay: timestamp - Time.now.to_f)
+      end
+
+      def enqueue_all(jobs)
+        dispatcher.dispatch_all(jobs)
+      end
+
+      private
+
+      # Resolved per call, so the app boots without a managed queue.
+      def dispatcher
+        (@runtime || LaravelCloud::Queue.runtime).dispatcher
+      end
+    end
+  end
+end

data/lib/laravel-cloud-rails.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+# Bundler requires a gem by its name, so `gem "laravel-cloud-rails"` lands here.
+require_relative "laravel_cloud"

data/lib/laravel_cloud/cli.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "optparse"
+
+module LaravelCloud
+  # `laravel-cloud queue:work [options]`, the queue worker Laravel Cloud runs.
+  # Boots the app from config/environment.rb, so run it from the app root.
+  class CLI
+    def initialize(argv, out: $stdout, err: $stderr, boot: true)
+      @argv = argv.dup
+      @out = out
+      @err = err
+      @boot = boot
+    end
+
+    def run
+      command = @argv.shift
+
+      case command
+      when "queue:work" then work
+      when "-v", "--version"
+        @out.puts("laravel-cloud #{VERSION}")
+        0
+      else
+        @err.puts(command.nil? || %w[-h --help].include?(command) ? usage : "Unknown command #{command.inspect}.\n\n#{usage}")
+        command.nil? || %w[-h --help].include?(command) ? 0 : 1
+      end
+    rescue OptionParser::ParseError => e
+      @err.puts("#{e.message}\n\n#{usage}")
+      1
+    rescue LaravelCloud::Error => e
+      # Expected failures exit non-zero without a backtrace; on Cloud that
+      # restarts the container.
+      @err.puts("[LaravelCloud] #{e.message}")
+      1
+    end
+
+    private
+
+    def work
+      options = { queues: [] }
+
+      parser = OptionParser.new do |opts|
+        opts.banner = "Usage: laravel-cloud queue:work [options]"
+        opts.on("-q", "--queue NAME", "Queue(s) to poll without the Cloud agent, in order; repeat or comma-separate") do |value|
+          options[:queues].concat(value.split(",").map(&:strip).reject(&:empty?))
+        end
+        opts.on("--tries N", Integer, "Times a job that raises is attempted in all (default 1)") { |value| options[:tries] = value }
+        opts.on("--backoff SECONDS", Integer, "Wait before re-attempting a job that raised (default 0)") { |value| options[:backoff] = value }
+        opts.on("--max-jobs N", Integer, "Stop after processing N jobs") { |value| options[:max_jobs] = value }
+        opts.on("--max-time SECONDS", Integer, "Stop after running for this long") { |value| options[:max_time] = value }
+        opts.on("--shutdown-timeout SECONDS", Integer, "Time a running job gets to finish on shutdown (default 15)") do |value|
+          options[:shutdown_timeout] = value
+        end
+        opts.on("--stop-when-empty", "Exit once the queues are drained") { options[:stop_when_empty] = true }
+      end
+
+      parser.parse!(@argv)
+      boot_app
+
+      Queue::Worker.new(**options).run
+      0
+    end
+
+
+    def boot_app
+      return unless @boot
+
+      environment = File.expand_path("config/environment.rb")
+
+      unless File.exist?(environment)
+        raise LaravelCloud::Error, "No Rails application found: run laravel-cloud from the application root (#{environment} is missing)."
+      end
+
+      require environment
+
+      # Booting this way skips eager loading, which a long-lived worker wants.
+      Rails.application.eager_load! if Rails.application.config.eager_load
+    end
+
+    def usage
+      <<~USAGE
+        Usage: laravel-cloud <command> [options]
+
+        Commands:
+          queue:work                 Process Laravel Cloud managed queue jobs (--help for options)
+      USAGE
+    end
+  end
+end

data/lib/laravel_cloud/events.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require "json"
+require "socket"
+
+module LaravelCloud
+  # Writes dashboard events to the Cloud log socket as newline-delimited JSON.
+  # A port of Laravel's Cloud\Events. Failures are swallowed: observability
+  # must never take down a job or a request.
+  class Events
+    TIMEOUT = 2
+
+    # e.g. "unix:///tmp/cloud-init.sock", or a bare path.
+    def initialize(address)
+      @path = address.to_s.delete_prefix("unix://")
+      @socket = nil
+
+      # Request threads all enqueue, so lock to keep lines from interleaving.
+      @mutex = Mutex.new
+    end
+
+    def emit(payload)
+      emit_many([payload])
+    end
+
+    def emit_many(payloads)
+      return if payloads.empty?
+
+      line = payloads.map { |payload| JSON.generate(scrub(payload)) }.join("\n") << "\n"
+
+      @mutex.synchronize do
+        ensure_connected
+        write(line)
+      end
+    rescue StandardError
+    end
+
+    private
+
+    # Like Laravel's JSON_INVALID_UTF8_SUBSTITUTE: bad bytes become U+FFFD.
+    # Ruby's JSON would raise instead, silently dropping the event.
+    def scrub(value)
+      case value
+      when String then value.valid_encoding? && value.encoding == Encoding::UTF_8 ? value : value.dup.force_encoding(Encoding::UTF_8).scrub("\uFFFD")
+      when Hash then value.to_h { |key, item| [scrub(key), scrub(item)] }
+      when Array then value.map { |item| scrub(item) }
+      else value
+      end
+    end
+
+    def write(line)
+      @socket.write(line)
+    rescue StandardError
+      # The stream may hold a half-written line; reconnect on the next emit.
+      disconnect
+      raise
+    end
+
+    def ensure_connected
+      connect unless connected?
+    end
+
+    def connect
+      socket = Socket.unix(@path)
+      socket.timeout = TIMEOUT
+      @socket = socket
+    end
+
+    # A non-blocking read tells a closed peer (EOF) from a healthy idle socket
+    # (nothing to read). The collector never writes back.
+    def connected?
+      return false if @socket.nil? || @socket.closed?
+
+      if @socket.read_nonblock(1, exception: false).nil?
+        disconnect
+        return false
+      end
+
+      true
+    rescue StandardError
+      disconnect
+      false
+    end
+
+    def disconnect
+      @socket&.close
+    rescue StandardError
+      # Already gone.
+    ensure
+      @socket = nil
+    end
+  end
+end

data/lib/laravel_cloud/queue/agent_client.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "json"
+require "net/http"
+require "socket"
+
+module LaravelCloud
+  module Queue
+    # Talks to the Cloud agent over its unix socket. The agent long-polls SQS,
+    # hands messages over on GET /next, and on POST /result performs the
+    # delete or visibility change itself.
+    class AgentClient
+      # The agent is unreachable or erroring. It only recovers on restart, so
+      # the worker exits; SQS redelivers anything in flight.
+      class Unavailable < LaravelCloud::Error; end
+
+      # The agent refused one outcome (HTTP 4xx); the worker logs it and moves on.
+      class Rejected < LaravelCloud::Error; end
+
+      # Longer than the agent's ~55s poll, so a poll never times out early.
+      NEXT_TIMEOUT = 65
+      RESULT_TIMEOUT = 10
+      RESULT_ATTEMPTS = 3
+
+      # The agent hasn't seen the request yet, so these are safe to retry.
+      CONNECT_ERRORS = [Errno::ENOENT, Errno::ECONNREFUSED].freeze
+
+      # The agent may already have acted, so these aren't retried.
+      TRANSPORT_ERRORS = [
+        Errno::ECONNRESET, Errno::EPIPE, EOFError, IOError,
+        Net::ReadTimeout, Net::WriteTimeout, Net::OpenTimeout, Net::HTTPBadResponse,
+      ].freeze
+
+      def initialize(socket_path)
+        @socket_path = socket_path
+      end
+
+      # The next message (messageId, receiptHandle, body, attributes, queueUrl),
+      # or nil when there's none.
+      def next_message
+        response = request(Net::HTTP::Get.new("/next"), timeout: NEXT_TIMEOUT)
+
+        return nil if response.code == "204"
+
+        raise Unavailable, "The Laravel Cloud agent returned HTTP #{response.code} from GET /next." unless response.code == "200"
+
+        data = JSON.parse(response.body.to_s)
+        raise Unavailable, "The Laravel Cloud agent returned a non-object body from GET /next." unless data.is_a?(Hash)
+
+        data
+      rescue JSON::ParserError
+        raise Unavailable, "The Laravel Cloud agent returned a malformed body from GET /next."
+      end
+
+      # "processed" deletes the message; "released" redelivers it after `delay`
+      # seconds. There's no "failed" outcome — failures are reported as
+      # "processed" and surfaced through observability.
+      def report(message_id, receipt_handle, status, delay: nil)
+        payload = {
+          "messageId" => message_id,
+          "receiptHandle" => receipt_handle,
+          "status" => status,
+          "delay" => delay,
+        }.compact
+
+        attempts = 0
+
+        begin
+          attempts += 1
+
+          post = Net::HTTP::Post.new("/result", "Content-Type" => "application/json")
+          post.body = JSON.generate(payload)
+
+          response = request(post, timeout: RESULT_TIMEOUT, retry_connect: attempts < RESULT_ATTEMPTS)
+        rescue RetryableConnectionError
+          sleep 0.1
+          retry
+        end
+
+        code = response.code.to_i
+
+        raise Unavailable, "The Laravel Cloud agent returned HTTP #{code} from POST /result." if code >= 500
+        raise Rejected, "The Laravel Cloud agent rejected the result with HTTP #{code}." if code >= 400
+
+        nil
+      end
+
+      private
+
+      class RetryableConnectionError < StandardError; end
+      private_constant :RetryableConnectionError
+
+      def request(request, timeout:, retry_connect: false)
+        http = UnixHTTP.new("localhost")
+        http.socket_path = @socket_path
+        http.open_timeout = timeout
+        http.read_timeout = timeout
+        http.write_timeout = timeout
+        # Never re-issue a long-poll; #report retries on its own terms.
+        http.max_retries = 0
+
+        http.start { |connection| connection.request(request) }
+      rescue *CONNECT_ERRORS => e
+        raise RetryableConnectionError if retry_connect
+
+        raise Unavailable, "The Laravel Cloud agent runtime socket is unreachable (#{e.class}: #{e.message})."
+      rescue *TRANSPORT_ERRORS => e
+        raise Unavailable, "The Laravel Cloud agent request failed (#{e.class}: #{e.message})."
+      end
+
+      # Net::HTTP over a unix socket instead of TCP.
+      class UnixHTTP < Net::HTTP
+        attr_accessor :socket_path
+
+        private
+
+        def connect
+          socket = begin
+            UNIXSocket.new(socket_path)
+          rescue ArgumentError => e
+            # e.g. a path over the OS's ~104-byte limit: not worth retrying.
+            raise Unavailable, "The Laravel Cloud agent socket path #{socket_path.inspect} is unusable: #{e.message}"
+          end
+
+          @socket = Net::BufferedIO.new(
+            socket,
+            read_timeout: @read_timeout,
+            write_timeout: @write_timeout,
+            continue_timeout: @continue_timeout,
+            debug_output: @debug_output,
+          )
+
+          on_connect
+        end
+      end
+      private_constant :UnixHTTP
+    end
+  end
+end

data/lib/laravel_cloud/queue/delivery.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require "active_support/isolated_execution_state"
+
+module LaravelCloud
+  module Queue
+    # A received message and its outcome so far.
+    #
+    # The worker makes it *current* while the job runs. `retry_on` re-enqueues
+    # a dup of the job with the same job_id, so the adapter can recognise the
+    # retry and record a release here instead of pushing a duplicate — the
+    # equivalent of Laravel's `$job->release($delay)`.
+    class Delivery
+      STATE_KEY = :laravel_cloud_queue_delivery
+
+      attr_reader :message_id, :receipt_handle, :queue_url, :queue, :body, :receive_count, :job_id, :job_queue_name,
+                  :release_delay
+
+      def self.within(delivery)
+        previous = current
+        ActiveSupport::IsolatedExecutionState[STATE_KEY] = delivery
+        yield
+      ensure
+        ActiveSupport::IsolatedExecutionState[STATE_KEY] = previous
+      end
+
+      def self.current
+        ActiveSupport::IsolatedExecutionState[STATE_KEY]
+      end
+
+      # `receive_count` is SQS's ApproximateReceiveCount.
+      def initialize(message_id:, receipt_handle:, queue_url:, queue:, body:, receive_count:, from_agent:)
+        @message_id = message_id
+        @receipt_handle = receipt_handle
+        @queue_url = queue_url
+        @queue = queue
+        @body = body
+        @receive_count = [receive_count.to_i, 1].max
+        @from_agent = from_agent
+        @job_id = nil
+        @job_queue_name = nil
+        @release_delay = nil
+        @superseded = false
+      end
+
+      def from_agent?
+        @from_agent
+      end
+
+      def bind(job_data)
+        @job_id = job_data["job_id"]
+        @job_queue_name = job_data["queue_name"]
+        self
+      end
+
+      # Whether enqueueing `job` is a retry of the running job.
+      def retry_of?(job)
+        !job_id.nil? && job.job_id == job_id
+      end
+
+      def release!(delay)
+        @release_delay = delay
+        @superseded = false
+      end
+
+      # The retry was pushed to another queue, so delete the original.
+      def supersede!
+        @release_delay = nil
+        @superseded = true
+      end
+
+      def released?
+        !@release_delay.nil?
+      end
+
+      def retried?
+        released? || @superseded
+      end
+    end
+  end
+end