07_serverprog.asc #2

== Server Programming

=== Including New Rack Middleware

Additional methods can be added as part of the core Helix Web Services server.

Adding new HTTP methods to the API should probably be done in a module specific to your extension, which forms a kind of namespace.
By convention, we create a `MyModule::App` class that inherits from `Sinatra::Base`, to define the API to your module.
Also, by convention, we prefix methods to your module with a simple string path, e.g., `my_module`.

Say we want the ability to fetch "stuff" from your module.
You would create a Sinatra modular app in a `my_module/app.rb` file:

[source,ruby]
.my_module/app.rb
----
module MyModule
  class App < Sinatra::Base
     get '/my_module/v1/stuff`
        # We use p4, so make sure you have a p4 connection available
        require_p4

        # If there's a problem, we'll actually handle exceptions for you
        results = env['p4'].run_print('-o', '//depot/stuff')

        # Right now, we only produce JSON.
        results.to_json
     end
  end
end
----

Typically, you'd reference this in a `my_module.rb` file, which imports your App, and possibly defines helper methods in your namespace.

[source,ruby]
.my_module.rb
----
require 'my_module/app'

module MyModule
  def helper_method
    # do something
  end
end
----

The final step is to include your modular app in the top level `HelixWebServices` application.

[source,ruby]
.helix_web_services.rb
----
# ... truncated other things
require 'my_module'

module HelixWebServices
  class Master < Sinatra::Base
    # ... lots of things are truncated

    register_app(MyModule::App)
  end
end
----

Additionally, a method `use_after_settings` can run custom middleware after
we've initialized our per-request configuration.

This will allow you to create special rules that, say, blocks invalid `P4PORT`
values, such that applications can't use your HWS instance to ping an unexpected
perforce instance.

[source,ruby]
----
require 'json'

class CustomMiddleware
	def initialize(app)
		@app = app
	end

	def call(env)
	    # Only allow 'localhost:1666' as the P4PORT value
		if env['hws_settings'].P4PORT != 'localhost:1666'
			return [
				400,
	            { 'Content-Type' => 'text/plain',
	              'Content-Length' => '0' },
	            []
		    ]
			raise "localhost:1666 connections only"
		end
		return @app.call(env)
	end
end

HelixWebServices::Master.use_after_settings CustomMiddleware
----



=== Registering Configuration Variables

If your application requires new configuration, you should:

1. Declare your variables in `hws_settings.rb`
2. Document your variables in `doc/03_configuration.asc`

If you follow these steps, your configuration variables will be a part of the `env['hws_settings']` hashes available to each Sinatra method.




[[project_extensions]]
=== Adding Project Extensions

A project extension is a combination of JSON metadata and logic that can be used for product-specific integrations, or optional features.

Creating a project extension involves the following tasks:

1. Define the JSON extension, typically by documenting it
2. Assign a simple extension ID and versioned MIME-style content type.
3. Implement logic and assign to callbacks of the link:./helix_web_services/Projects/ProjectService.html[ProjectService] class

Your extension should probably append handlers to the following methods:

- link:./helix_web_services/Projects/ProjectService.html#append_to_list-class_method[Projects::ProjectService.append_to_list]
- link:./helix_web_services/Projects/ProjectService.html#fetch_project-class_method[Projects::ProjectService.fetch_project]