github.com/Comcast/plax@v0.8.32/dsl/chan.go (about)

     1  /*
     2   * Copyright 2021 Comcast Cable Communications Management, LLC
     3   *
     4   * Licensed under the Apache License, Version 2.0 (the "License");
     5   * you may not use this file except in compliance with the License.
     6   * You may obtain a copy of the License at
     7   *
     8   * http://www.apache.org/licenses/LICENSE-2.0
     9   *
    10   * Unless required by applicable law or agreed to in writing, software
    11   * distributed under the License is distributed on an "AS IS" BASIS,
    12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    13   * See the License for the specific language governing permissions and
    14   * limitations under the License.
    15   *
    16   * SPDX-License-Identifier: Apache-2.0
    17   */
    18  
    19  package dsl
    20  
    21  import "time"
    22  
    23  var (
    24  	// DefaultChanBufferSize is a default buffer size any Chan can
    25  	// choose to consider.
    26  	DefaultChanBufferSize = 1024
    27  )
    28  
    29  type Msg struct {
    30  	Topic      string    `json:"topic"`
    31  	Payload    string    `json:"payload"`
    32  	ReceivedAt time.Time `json:"receivedAt"`
    33  }
    34  
    35  // ChanOpts represents generic data that is give to a Chan constructor.
    36  type ChanOpts interface{}
    37  
    38  // ChanKind is something like 'mqtt', 'kds', etc.
    39  //
    40  // Support for a Chan registers itself in ChanRegistry.
    41  type ChanKind string
    42  
    43  // ChanMaker is the signature for a Chan constructor.
    44  type ChanMaker func(ctx *Ctx, def interface{}) (Chan, error)
    45  
    46  // ChanRegistry maps a ChanKind to a constructor for that type of
    47  // Chan.
    48  type ChanRegistry map[ChanKind]ChanMaker
    49  
    50  func (r ChanRegistry) Register(ctx *Ctx, kind ChanKind, maker ChanMaker) {
    51  	r[kind] = maker
    52  }
    53  
    54  // TheChanRegistry is the global, well-known registry of supported
    55  // Chan types.
    56  var TheChanRegistry = make(ChanRegistry)
    57  
    58  // Chan can send and receive messages.
    59  type Chan interface {
    60  	// Open starts up the Chan.
    61  	Open(ctx *Ctx) error
    62  
    63  	// Chose shuts down this Chan.
    64  	Close(ctx *Ctx) error
    65  
    66  	// Kill ungracefully closes an underlying connection (if any).
    67  	//
    68  	// Useful for testing MQTT LWT.
    69  	Kill(ctx *Ctx) error
    70  
    71  	// Kind returns this Chan's type.
    72  	Kind() ChanKind
    73  
    74  	// Sub, when required, initials a subscription.
    75  	//
    76  	// Use the Recv method to obtain messages that arrive via any
    77  	// subscription.
    78  	Sub(ctx *Ctx, topic string) error
    79  
    80  	// Recv returns a channel of messages.
    81  	Recv(ctx *Ctx) chan Msg
    82  
    83  	// Pub, when supported, publishes a message on this Chan.
    84  	Pub(ctx *Ctx, m Msg) error
    85  
    86  	// To is a utility to send a message to the channel returned
    87  	// by Recv.
    88  	To(ctx *Ctx, m Msg) error
    89  
    90  	DocSpec() *DocSpec
    91  }