* gateio: Add multi asset websocket support WIP.
* meow
* Add tests and shenanigans
* integrate flushing and for enabling/disabling pairs from rpc shenanigans
* some changes
* linter: fixes strikes again.
* Change name ConnectionAssociation -> ConnectionCandidate for better clarity on purpose. Change connections map to point to candidate to track subscriptions for future dynamic connections holder and drop struct ConnectionDetails.
* Add subscription tests (state functional)
* glorious:nits + proxy handling
* Spelling
* linter: fixerino
* instead of nil, dont do nil.
* clean up nils
* cya nils
* don't need to set URL or check if its running
* stop ping handler routine leak
* * Fix bug where reader routine on error that is not a disconnection error but websocket frame error or anything really makes the reader routine return and then connection never cycles and the buffer gets filled.
* Handle reconnection via an errors.Is check which is simpler and in that scope allow for quick disconnect reconnect without waiting for connection cycle.
* Dial now uses code from DialContext but just calls context.Background()
* Don't allow reader to return on parse binary response error. Just output error and return a non nil response
* Allow rollback on connect on any error across all connections
* fix shadow jutsu
* glorious/gk: nitters - adds in ws mock server
* linter: fix
* fix deadlock on connection as the previous channel had no reader and would hang connection reader for eternity.
* gk: nits
* Leak issue and edge case
* gk: nits
* gk: drain brain
* glorious: nits
* Update exchanges/stream/websocket.go
Co-authored-by: Scott <gloriousCode@users.noreply.github.com>
* glorious: nits
* add tests
* linter: fix
* After merge
* Add error connection info
* Fix edge case where it does not reconnect made by an already closed connection
* stream coverage
* glorious: nits
* glorious: nits removed asset error handling in stream package
* linter: fix
* rm block
* Add basic readme
* fix asset enabled flush cycle for multi connection
* spella: fix
* linter: fix
* Add glorious suggestions, fix some race thing
* reinstate name before any routine gets spawned
* stop on error in mock tests
* glorious: nits
* glorious: nits found in CI build
* Add test for drain, bumped wait times as there seems to be something happening on macos CI builds, used context.WithTimeout because its instant.
* mutex across shutdown and connect for protection
* lint: fix
* test time withoffset, reinstate stop
* fix whoops
* const trafficCheckInterval; rm testmain
* y
* fix lint
* bump time check window
* stream: fix intermittant test failures while testing routines and remove code that is not needed.
* spells
* cant do what I did
* protect race due to routine.
* update testURL
* use mock websocket connection instead of test URL's
* linter: fix
* remove url because its throwing errors on CI builds
* connections drop all the time, don't need to worry about not being able to echo back ws data as it can be easily reviewed _test file side.
* remove another superfluous url thats not really set up for this
* spawn overwatch routine when there is no errors, inline checker instead of waiting for a time period, add sleep inline with echo handler as this is really quick and wanted to ensure that latency is handing correctly
* linter: fixerino uperino
* glorious: panix
* linter: things
* whoops
* defer lock and use functions that don't require locking in SetProxyAddress
* lint: fix
* thrasher: nits
---------
Co-authored-by: shazbert <ryan.oharareid@thrasher.io>
Co-authored-by: Scott <gloriousCode@users.noreply.github.com>
* CI/build: Update Go version, linters and fix minor issues
* linters: Add intrange, copyloopvar, additional go vet linters to match gopls and fix issues
* Websocket: Use ErrSubscribedAlready
instead of errChannelAlreadySubscribed
* Subscriptions: Replace Pair with Pairs
Given that some subscriptions have multiple pairs, support that as the
standard.
* Docs: Update subscriptions in add new exch
* RPC: Update Subscription Pairs
* Linter: Disable testifylint.Len
We deliberately use Equal over Len to avoid spamming the contents of large Slices
* Websocket: Add suffix to state consts
* Binance: Subscription Pairs support
* Bitfinex: Subscription Pairs support
* Bithumb: Subscription Pairs support
* Bitmex: Subscription Pairs support
* Bitstamp: Subscription Pairs support
* BTCMarkets: Subscription Pairs support
* BTSE: Subscription Pairs support
* Coinbase: Subscription Pairs support
* Coinut: Subscription Pairs support
* GateIO: Subscription Pairs support
* Gemini: Subscription Pairs support and improvement
* Hitbtc: Subscription Pairs support
* Huboi: Subscription Pairs support
* Kucoin: Subscription Pairs support
* Okcoin: Subscription Pairs support
* Poloniex: Subscription Pairs support
* Kraken: Add subscription Pairs support
Note: This is a naieve implementation because we want to rebase the
kraken websocket rewrite on top of this
* Bybit: Subscription Pairs support
* Okx: Subscription Pairs support
* Bitmex: Subsription configuration
* Fixes unauthenticated websocket left as CanUseAuth
* Fixes auth subs happening privately
* CoinbasePro: Subscription Configuration
* Consolidate ProductIDs when all subscriptions are for the same list
* Websocket: Log actual sent message when Verbose
* Subscriptions: Improve clarity of which key is which in Match
* Subscriptions: Lint fix for HugeParam
* Subscriptions: Add AddPairs and move keys from test
* Subscriptions: Simplify subscription keys and add key types
* Subscriptions: Add List.GroupPairs Rename sub.AddPairs
* Subscription: Fix ExactKey not matching 0 pairs
* Subscriptions: Remove unused IdentityKey and HasPairKey
* Subscriptions: Fix GetKey test
* Subscriptions: Test coverage improvements
* Websocket: Change State on Add/Remove
* Subscriptions: Improve error context
* Subscriptions: Fix Enable: false subs not ignored
* Bitfinex: Fix WsAuth test failing on DataHandler
DataHandler is eaten by dataMonitor now, so we need to use ToRoutine
* Deribit: Subscription Pairs support
* Websocket: Accept nil lists for checkSubscriptions
If the user passes in a nil (implicitly empty) list, we would not panic.
Therefore the burden of correctness about that data lies with them.
The list of subscriptions is empty, and that's okay, and possibly
convenient
* Websocket: Add context to NilPointer errors
* Subscriptions: Add context to nil errors
* Exchange: Fix error expectations in UnsubToWSChans
* Websocket: Remove IsInit and simplify SetProxyAddress
IsInit was basically the same as IsConnected.
Any time Connect was called both would be set to true.
Any time we had a disconnect they'd both be set to false
Shutdown() incorrectly didn't setInit(false)
SetProxyAddress simplified to only reconnect a connected Websocket.
Any other state means it hasn't been Connected, or it's about to
reconnect anyway.
There's no handling for IsConnecting previously, either, so I've wrapped
that behind the main mutex.
* Websocket: Expand and Assertify tests
* Websocket: Simplify state transistions
* Websocket: Simplify Connecting/Connected state
* Websocket: Tests and errors for websocket
* Websocket: Make WebsocketNotEnabled a real error
This allows for testing and avoids the repetition.
If each returned error is a error.New() you can never use errors.Is()
* Websocket: Add more testable errors
* Websocket: Improve GenerateMessageID test
Testing just the last id doesn't feel very robust
* Websocket: Protect Setup() from races
* Websocket: Use atomics instead of mutex
This was spurred by looking at the setState call in trafficMonitor and
the effect on blocking and efficiency.
With the new atomic types in Go 1.19, and the small types in use here,
atomics should be safe for our usage. bools should be truly atomic,
and uint32 is atomic when the accepted value range is less than one byte/uint8 since
that can be written atomicly by concurrent processors.
Maybe that's not even a factor any more, however we don't even have to worry enough to check.
* Websocket: Fix and simplify traffic monitor
trafficMonitor had a check throttle at the end of the for loop to stop it just gobbling the (blocking) trafficAlert channel non-stop.
That makes sense, except that nothing is sent to the trafficAlert channel if there's no listener.
So that means that it's out by one second on the trafficAlert, because any traffic received during the pause is doesn't try to send a traffic alert.
The unstopped timer is deliberately leaked for later GC when shutdown.
It won't delay/block anything, and it's a trivial memory leak during an infrequent event.
Deliberately Choosing to recreate the timer each time instead of using Stop, drain and reset
* Websocket: Split traficMonitor test on behaviours
* Websocket: Remove trafficMonitor connected status
trafficMonitor does not need to set the connection to be connected.
Connect() does that. Anything after that should result in a full
shutdown and restart. It can't and shouldn't become connected
unexpectedly, and this is most likely a race anyway.
Also dropped trafficCheckInterval to 100ms to mitigate races of traffic
alerts being buffered for too long.
* Websocket: Set disconnected earlier in Shutdown
This caused a possible race where state is still connected, but we start
to trigger interested actors via ShutdownC and Wait.
They may check state and then call Shutdown again, such as
trafficMonitor
* Websocket: Wait 5s for slow tests to pass traffic draining
Keep getting failures upstream on test rigs.
Think they can be very contended, so this pushes the boundary right out
to 5s
* Websockets: Add keys to websocket subscriptions
* This switches all RO uses of the mutex to use a RLock method.
* The mutex used for discrete field access has had scope drift from
name 'connectionMutex' so rename to more appropriate fieldsMutex
* The mutex used for Set/CanUseAuthEndpoints moves from the
subscriptions endpoint to the fieldsMutex
* Add GetSubscription by key
* Expose stream.Matcher type
* Bitfinex: Subscribe and Unsubscribe atomicly
* Fix Auth failures ignored
* This change makes it so that Subscribe and Unsubscribe wait for success
** Tells the DataHandler about errors
** Errors are returned to consumers
* Subscribes concurrently to the channels
* It also simplifies the chanId to stream mapping
* Removes unable to locate chanID: %d errors which are just noise
* Paves the way for unified channelSubscription id handling
* Adds support for subId for Book subscriptions, which is more robust
* Vastly simplifies what we need to test TestWsSubscribedResponse
This test was working to ensure that the various fancy key parsing
mechanisms all worked. Now that we use subId, we just need a thorough
test of that
* Expose Match.Set in order to capture websocket incoming data
Can't see another way of doing this. Doesn't seem too bad
* Allow tests to run with auth or WS
These flags made it difficult to run the tests whilst working on
websockets
* Enable API auth and WS in testconfig
This change minimises the changes requires for a full test run against
live endpoints, so that new contributors have a clearer testing path.
I cannot see any reason to turn WS off and Auth endpoints off when we're
not going to run API tests without Creds being set, and we're not going
to do live fire tests without canManipulateRealOrders
* TestWsSubscribe and various fixes
** Enables the websocket for live non-authed integration tests by default
** Adds an integration test for subscriptions
** Changes the Ws tests to respect canManipulateRealOrders
** Uses WsConnect instead of setupWs; fixes seqNo config not sent for WS tests
** Allows api creds to live in config/testdata.json which might be
less likely to accidentally commit, and less obtrusive
* Bitfinex: Support period and timeframe for Candles
* Fixes manual Subscribe() symbol or key formatting
* Unifies handling of params for DefaultSubscriptions and manual
subsrciptions
* Bitfinex: Handle conf and info WS channel events
* Bitfinex: Better tests for subscriptions
* fixup! Websockets: Add keys to websocket subscriptions
* fixup! Bitfinex: Subscribe and Unsubscribe atomicly
* fixup! Websockets: Add keys to websocket subscriptions
* Websockets: Add Pending subscription status
Add a status tracker so that Sub/Unsub can prevent duplicates,
and also fixes when first message comes before we have added the sub
to the tracker
* Websockets: Add State instead of pending
This change allows more clarity about the current state and
checks for specifically already Unsubing
* Bitfinex: Fix first sub message maybe lost
The only link we have between a sub req and the sub resp is the subID.
And the only link we have between a sub message and the sub is the chanID.
We can't derive a link using Pair or anything else.
This meant that by sending the resp and its chanID down the IncomingData
channel, we allowed the channel reader to maybe process the next
message, the first message on the channel, before the runtime executed
the switch back to subscribeToChan waiting on the chan.
To fix this, we key initially on subId.(string), and then replace it
with chanId.(int64) when we have it *inside* the wsHandleData so we
know we've procedurally handled it before the next message.
subscribeToChan is then free to remove the subId keyed Sub regardless of
error or not
If there's an error, we don't need to inline handling because there
won't be any second update.
Expands test coverage to make sure those subId keyed subscriptions are
removed.
* Websocket: Validate state in SetChanState
* fixup! Bitfinex: Fix first sub message maybe lost
* Websockets: Rename RemoveUnsuccessfulSubs
Implementation doesn't imply Unsuccessful or need to.
This change supports the registering of Pending subs
* Bitfinex: Fix race in Tests
* WS: Relay disconnect errors to subscribers
Subscribers probably care when the WS got disconncted.
Tell them and expose a method to test the error for matching
* Fix linter error
* engine: shutdown and unload exchange when engine is stopped
* linter: fixes
* engine/exchMan: add nil check
* engine/exchanges: add shutdown method to exchanges, rm len check lock not needed, expanded code coverage, address some nits
* exchMan: report all failed shutdowns across exchanges, implement timer and monitoring routines.
* exchMan: improve shutdown sequence and aloc.
* further improvement
* exchman: log from warn to error
* websockconnection: Suppress error return when closure is caused by library
* linter: fix
* fix racies
* add note on why not parallel tests
* glorious: nits
* spelling kween
* thrasher: nits
* engine: change print of setting using reflection, I keep forgetting to implement this so program around forgetfulness
* engine/exchange_management: remove wait group and just rely on intermediary lock
* glorious: nits
* Update common/common.go
Co-authored-by: Adrian Gallagher <adrian.gallagher@thrasher.io>
* Update main.go
Co-authored-by: Adrian Gallagher <adrian.gallagher@thrasher.io>
---------
Co-authored-by: Ryan O'Hara-Reid <ryan.oharareid@thrasher.io>
Co-authored-by: Adrian Gallagher <adrian.gallagher@thrasher.io>
* Bump CI versions
* Specifically set go version as 1.17.x bumps it to 1.18
* Another
* Adjust AppVeyor
* Part 1 of linter issues
* Part 2
* Fix various linters and improvements
* Part 3
* Finishing touches
* Tests and EqualFold
* Fix nitterinos plus bonus requester jobs bump for exchanges with large number of tests
* Fix nitterinos and bump golangci-lint timeout for AppVeyor
* Address nits, ensure all books are returned on err due to syncer regression
* Fix the wiggins
* Fix duplication
* Fix nitterinos
* websocket: select case error if no receiver, add in functionality to reset to initial sync for books on a new websocket connection
* websocket: fix tests
* websocket: log error instead of losing it
* websocket: fix whoopsie
* exchanges: fix test
* websocket: force requirement of specific functionality
* exchanges: fix tests
* exchanges/websocket: move waitgroup add before scheduling across exchanges
* gateio: add feature subscribe
* bithumb/bittrex: include connection state reset, fix reconnection bug for Bithumb
* huobi: Add listen to shutdown to routine so it actually returns and stops being a naughty boy.
* huobi: add missing waitgroup add.
* exchanges: bleed comms channels
* binance: fix reconnection bug with buffer
* bithumb: fix reconnection bug with ws orderbook when websocket is diabled/enabled
* bithumb/bittrex: add bleeders for ws orderbook jobs
* linter: fix
* kraken: reduce code block from double assertion
* This bug ruined my day.
* glorious: error checking
* zb: add correct path for websocket connection
* exchange: Add verbosity when config conflicts and overwrites default values
* zb: add https to path
* exchanges: glorious nits
* stream: Add checkAndSetMonitoring to reduce potential routine bundling, increase timeout and check state in tests
* stream: remove check that is not needed.
* glorious: nits addr.
* lint: test
* initial update of currency system
* WIP progress
* Finish initial currency string error returns
* fix whoopsie testing for non https insecureinos
* Current WIP for getEnabledPairs check and error return
* WIP continued
* When getting enabled pairs throw error when item is not contained in available pairs list
* More updates -WIP
* Wip continued including potential interface
* Current WIP
* pairs manager pass
* drop asset string and just use the map key, plus return some errors and create more work for myself.
* clean and fixed a bug in currency.json, will not populate correctly without coinmarketcap api keys set.
* purge logger references after merge
* go mod tidy after merge
* Pointer change WIP
* fix some issues and added error returns to a few items (WIP)
* WIP
* Clean
* Fix some linter issues
* Fix more linter issues
* even more linters
* xtda nits
* revert pointer change and rm field
* Addr madcozbadd nits
* fix linter issues: shadow declarations
* Fix linter issues: gocritic huge things
* linter issue fix
* Addr nits
* flush go mod files
* after merge woops
* fix shadow dec
* Addr thrasher nits
* addr nits
* fix some issues
* more fixes
* RM println
* Addr glorious nits
* Add helper method for setting assets
* add missing format directive
* Addr nits
* Actually process new futures contracts -_- derp
* WIP for GRPC upgrade for pair management
* update config pairs
* finished disabling and enabling asset
* linked update of tradable pairs to cli
* fix oopsies
* defer writing to file on program termination for currency storage system
* update template
* don't add disabled asset items to initial sync
* Fix enable disabling a list of pairs and added in a slice error type so we can add whats allowable without throwing an error and return a report, also addressed some other nits
* WIP on getting a channel to unsub
* Wip track down unsubscribe bug and start creating streaming interface
* purge websocket orderbook object and centralised updating routine for orderbook
* general clean before interface implementation
* stage one connection interface WIP
* WIP
* repackage wshandler WIP
* find difference of subs and change signature of subscriber functions so we can batch subscriptions and unsubscription in exchanges that support it
* design change on mange subscription routine WIP
* integrated ZB with the new webosocket updates
* WIP - okex conversion
* integrate websocket upgrades for lakebtc, kraken, huobi, hitbtc, gateio, and WIP for coinbene
* integrate another range of exchanges for websocket update
* Added subscriber and unsubscriber methods to websocket functionality
* fixed tests WIP
* amalgamate cache setup with main websocket setup
* reinstate exported fields traffic alert and shutdownC to accommodate gemini and lakebtc implementations
* added in colon
* Updated websocket auth handling as they werent getting passed through. Added a setter method for websocket URL due to the Binance generated auth key/listenKey. Fixed bug which stopped reconnection.
* Fix subscribe candle bug
Fix time conversion in candle
Fix inititial candle history to datahandler
Include funding to orderbook handling
Include funding to trades
Reduce code duplication in sub and unsub functions
Added the ability to include funding currency websocket subscriptions
validated all channels and added more items todo list (Auth items)
* RM line
* bitstamp pass
* btcmarkets pass - still needs to implement unsubscriber functionality and pairs change test.
* Batch outgoing subscriptions and fix unsubscribe bug
* BTSE - bumped time to minute to reduce pinger calling by 75 calls per day. Fix authentication bug and add authentication pass into to-do. Batch outgoing subscription calls
* fix type field and batch outgoing subs and unsubs for coinbasepro
* Batch outgoing subs and unsubs
* Fixes bug when matching return from authentication
* Fix bug where params where being sent out of order due to map ,where depth items werent being subscribed too, where trying to subscribe to too many kline items caused error, where trying to get a nano secocond ID conflicted due to speed of generation.
* Add websocket capability for currency pair change by utilizing full channel subscription list in subscribe function.
* Add error handling
* Fix public: time conversions, subscription list, stopped pushing heartbeat to data handler, aggregated list of connections.
* hitBTC pass
* returned nil instead of error due to period null bids and asks updates coming through.
* Fix auth ping capture and reply. Added in interval handling for kline data. Added correct full trade data handling. Fix subscribe and unsubscribe.
* Fix when websocket auth conn and token generation fail we don't try and auth sub. Fix bug between auth and normal connection id generation and matching. Batch outgoing payloads to increase efficiency. Updated matching functions to utilise channels instead of waitgroups and go routines.
* RM debug output
* rm func to get shutdown channel
* Add unsubscriber functionality, added wsTicker type, removed return as this will impede data flow and cause reconnection when handling and processing data
* okgroup WIP
* *Added missing fields for websocket trades
*Fix bug processing kline interval
*Added fields for websocket ticker struct
*Fix auth bug
-Updated request and response matching param to interface so we can custom signature match. Stops auth subscribing before a reply is issued.
-Updated channel inclusion of pair fo auth subs as this was missing.
*Assortment of perfomance improvements
* poloniex pass
* send all trades to data handler, validated enabled and disable pairs
* initial clean
* centralised request matching mechanism
* websocket main improvements WIP
* WIP
* Websocket management via gctcli WIP
* GRPC expansion
* Updated GCTCLI with websocket url and proxy setting functionality which flushes connection
* Fix continuous spawning of routines bug on error with reconnection
* Addr linter issues
* fix subscription bug that I caused when I changed to a switch case
* fix linter issue
* fix woopsie
* End of day WIP
* Fix order submission REST, time conversion, order type conversion, orderID bugs
* fix gateio test and unsubscribe bug
* revert comment out code
* websocketAPI changed to to true in configtest.json
* fix race in gateio test
* End of day WIP for websocket tests.
* BugFix for binance when book isn't seeded. Updated websocket tests. Deprecated subscription manager. RM wrapper funcs.
* Added string title to exchange name as they are saved as lower case in type, reinstated verbose check in websocket.go
* Added verbosity check for setting websocket URL
* fix bug where the asset had a mind of its own
* purge dodgy coding
* Fix tests, drop blocking chan in websocket Dial function
* few more changes
* race condition fix for websocket tests.
* fix intermittent test failure due to underlying hash table storage
* Address madcuzbad nit
* RM superfluous printlines
* Add quick top example with paramater fields
* First pass Glorious nits
* As per madcozbad suggestion return error when enabled pair not found in full return map. Add test.
* addr madcozbadd nits
* as per glorious suggestion rm'd loadedJSON field
* adjusted ticker, added test and RM'd code that can never be executed
* Addr nits and add in crypto rand genration for ID's
* remove global channel declaration and rescoped as this was causing a lock
* as per glorious suggestion restructured return error for websocket
* addr glorious suggestions
* fix linter issues
* purge non-existent pair from testdata
* add side field to struct and parse
* addr glorious nits
* Add verbosity to error returns and logs and fix string parsing in GCTRPC
* fix speeling mistwake
* Adds websocket functionality check before flushing websocket connection
* Addr kraken panic and setting/flush websocket url stage one.
* added websocket url check before setting with tests
* Added in edge case test if by the time we call contains on available pairs it has been changed
* remove error return for func
* Continuation of tests
* continuation of tests
* Stop potential panic within pair creation function
* Implement changes to upstream
* rm sup comment
* fix bug when subscribing and unsubscribing. Also add in boolean to determine there are currencies that need to be flushed via set pairs via gctcli
* fix test
* Fix linter issues
* Fix tests
* turn websocket off in config example
* Fix issue where you cannot enable websocket when config is set to false, also added config websocket enable state saving
* Introduced err var for same error returns
* Add err var exchange base not found
* restructure function
* drop gctscript from generic response name
* drop managesub delay const as its not being used
* correctly implement websocket rate limiting for coinut
* remove quotations
* drop pair management check
* fix spelling
* return error in function to not update currency with unset role
* amalagamted enable/disable into set function and added in pairstore fetch function
* update error description
* rm function
* moved test function to sharedtestvals and move type to types.go
* append delimiter onto currency delimiter strings
* add test coverage
* rm functions as they are set as methods in base
* remove superfluous methods
* Fix issue that would occur when a subscription errored and not appending successful subs
* fix after rebase woopsie
* fix linter issues
* fix bug streamline code
* fix linter issues
* fix linter issues
* fix case where it should not change ID if set but append new
* fix whoopsie
* fix websocket tests
* fix readme, fix wrapper issues reporting template, go mod tidy
* add test coverage
* add test coverage and verified futures pariing
* add in futures bypass as its not currently supported on BTSE until API update and implementation
* removed downside/upside profit contract type as its no longer supported. Added in check in set config pairs to warn user of potential conflict and to manually remove or update.
* If asset enabled add pair and increase code coverage
* remove strings.title, set and fetch with strings.Lower but keep struct field exchangename unchanged. Streamline ticker and orderbook code.
* Add code coverage
* log error if setting default currency fails, add code coverage
* address glorious nits
* Addr xtda nits
* fix linter issues
* addr glorious nits
* xtda nits
* Addr glorious nits
* add subscription protection and removed a superfluous wait call
* fix test
* fix whoopsie
* addr xtda nits
* addr glorious nits
* Added asset types to subscriptions structs, also added in error handling for resubscription errors
* consolidated rpc returned type and added in sucessful strings
* dropped stream timing down to 100ms
* DOC changes
* proxy and url usage string additions
* WIP
* go mod tidy rides again
* Addr nits
* Addr nits, fix tests
* fix wording
* add in test case for currency matching
* Add byte length check on outbound websocket payload subscriptions
* addr thrasher nits
* Addr madcozbadd nits
* addr linter issues
* Addr glorious nits by amalgamating function into one mega amazing function.
* fix futures account subscription bug
* addr glorious nits and reinstated wg.Wait() checks
* changed string to currency delimiter string and setconnected by function
