rocketmq-client-nodejs/dist/consumer/LitePushConsumer.d.ts

RocketMQ Node.js Client

/**
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
import { BaseClientOptions } from '../client';
import { MessageListener } from './MessageListener';
import { OffsetOption } from './OffsetOption';
/**
 * LitePushConsumer interface for consuming messages from lite topics.
 *
 * <p>LitePushConsumer is a specialized consumer designed for lightweight scenarios
 * with reduced metadata and storage overhead. It supports dynamic subscription
 * management for lite topics.</p>
 */
export interface LitePushConsumer {
    /**
     * Subscribe to a lite topic.
     *
     * <p>The subscribeLite() method initiates network requests and performs quota verification,
     * so it may fail. It's important to check the result of this call to ensure that the
     * subscription was successfully added. Possible failure scenarios include:</p>
     * <ul>
     *   <li>Network request errors, which can be retried.</li>
     *   <li>Quota verification failures, indicated by LiteSubscriptionQuotaExceededException.
     *       In this case, evaluate whether the quota is insufficient and promptly unsubscribe
     *       from unused subscriptions using unsubscribeLite() to free up resources.</li>
     * </ul>
     *
     * @param liteTopic - The name of the lite topic to subscribe
     * @throws ClientException if an error occurs during subscription
     */
    subscribeLite(liteTopic: string): Promise<void>;
    /**
     * Subscribe to a lite topic with consumeFromOption to specify the consume from offset.
     *
     * @param liteTopic - The name of the lite topic to subscribe
     * @param offsetOption - The consume from offset option
     * @throws ClientException if an error occurs during subscription
     */
    subscribeLite(liteTopic: string, offsetOption: OffsetOption): Promise<void>;
    /**
     * Unsubscribe from a lite topic.
     *
     * @param liteTopic - The name of the lite topic to unsubscribe from
     * @throws ClientException if an error occurs during unsubscription
     */
    unsubscribeLite(liteTopic: string): Promise<void>;
    /**
     * Get the lite topic immutable set.
     *
     * @return Lite topic immutable set
     */
    getLiteTopicSet(): Set<string>;
    /**
     * Get the load balancing group for the consumer.
     *
     * @return Consumer load balancing group
     */
    getConsumerGroup(): string;
    /**
     * Close the consumer and release all related resources.
     *
     * <p>Once the consumer is closed, <strong>it could not be started once again.</strong>
     * We maintain an FSM (finite-state machine) to record the different states for each
     * push consumer.</p>
     */
    close(): Promise<void>;
}
export interface LitePushConsumerOptions extends BaseClientOptions {
    consumerGroup: string;
    bindTopic: string;
    messageListener: MessageListener;
    maxCacheMessageCount?: number;
    maxCacheMessageSizeInBytes?: number;
    consumptionThreadCount?: number;
    enableFifoConsumeAccelerator?: boolean;
}
/**
 * LitePushConsumer builder class.
 *
 * <p>This class provides a fluent API for configuring and creating
 * lite push consumers with reduced overhead for lightweight scenarios.</p>
 */
export declare class LitePushConsumerBuilder {
    private options;
    /**
     * Set the bind topic for the lite push consumer.
     *
     * @param bindTopic - The parent topic to bind
     * @return This builder instance
     * @throws Error if bindTopic is blank
     */
    bindTopic(bindTopic: string): LitePushConsumerBuilder;
    /**
     * Set the client configuration.
     *
     * @param options - Client configuration options
     * @return This builder instance
     * @throws Error if options is null/undefined
     */
    setClientConfiguration(options: BaseClientOptions): LitePushConsumerBuilder;
    /**
     * Set the consumer group.
     *
     * @param consumerGroup - Consumer group name
     * @return This builder instance
     * @throws Error if consumerGroup is null, doesn't match the pattern, or starts with 'GID-'
     */
    setConsumerGroup(consumerGroup: string): LitePushConsumerBuilder;
    /**
     * Set the message listener.
     *
     * @param messageListener - Message listener implementation
     * @return This builder instance
     * @throws Error if messageListener is null/undefined
     */
    setMessageListener(messageListener: MessageListener): LitePushConsumerBuilder;
    /**
     * Set the maximum cache message count.
     *
     * @param maxCacheMessageCount - Maximum number of messages to cache
     * @return This builder instance
     * @throws Error if maxCacheMessageCount is not positive
     */
    setMaxCacheMessageCount(maxCacheMessageCount: number): LitePushConsumerBuilder;
    /**
     * Set the maximum cache message size in bytes.
     *
     * @param maxCacheMessageSizeInBytes - Maximum cache size in bytes
     * @return This builder instance
     * @throws Error if maxCacheMessageSizeInBytes is not positive
     */
    setMaxCacheMessageSizeInBytes(maxCacheMessageSizeInBytes: number): LitePushConsumerBuilder;
    /**
     * Set the consumption thread count.
     *
     * @param consumptionThreadCount - Number of threads for consumption
     * @return This builder instance
     * @throws Error if consumptionThreadCount is not positive
     */
    setConsumptionThreadCount(consumptionThreadCount: number): LitePushConsumerBuilder;
    /**
     * Set enable fifo consume accelerator.
     *
     * <p>If enabled, messages with different messageGroups are consumed in parallel
     * while messages within the same messageGroup are consumed sequentially.</p>
     *
     * @param enableFifoConsumeAccelerator - Whether to enable FIFO consume accelerator
     * @return This builder instance
     */
    setEnableFifoConsumeAccelerator(enableFifoConsumeAccelerator: boolean): LitePushConsumerBuilder;
    /**
     * Finalize the build of LitePushConsumer and start.
     *
     * <p>This method will block until the push consumer starts successfully.
     *
     * <p>Especially, if this method is invoked more than once, different push consumers will be created and started.
     *
     * @return Promise resolving to started LitePushConsumer instance
     * @throws Error if required parameters are not set
     */
    build(): Promise<LitePushConsumer>;
}