Nettuts+

Win a Ticket to Our New Tuts+ Live Workshop

Joel Bankhead — Fri, 24 May 2013 17:30:15 +0000

We have 5 tickets to give away for our newest Tuts+ Live Workshop, all you have to do is subscribe to our newsletter. Be quick though, this giveaway ends on Monday!

We have a superb new Workshop, Introduction to WordPress Plugin Development, starting in a week. This is your chance to win a free ticket!

Simply subscribe to the Tuts+ Live Workshops newsletter and we’ll pick the winners on Monday 27th. Read on to find out more about the Workshop and for more details about the giveaway!

Introduction to WordPress Plugin Development

Our newest Tuts+ Live Workshop, Introduction to WordPress Plugin Development, teaches you everything that you need to know to start developing WordPress plugins; from setting up a local development environment, all the way through to building a WordPress plugin that’s ready for release into the WordPress Plugin Repository.

It’s led by Instructor Tom McFarlin, a self-employed WordPress developer who divides his time between running his own WordPress development shop, building plugins for WordPress, blogging every day about software development in the context of WordPress, and working for 8BIT (the team responsible for Standard Theme and WP Daily).

Each weekly workshop will last one hour, running over a five week period. You’ll have the opportunity to follow along with Tom, ask questions live during the workshop, and complete a weekly homework assignment. Not able to make it to the live recording? No problem! All of the workshop recordings will be made available online the day after the live workshop.

Learn more about Introduction to WordPress Plugin Development

Subscribe and Win a Ticket!

We have 5 tickets to give away and will be choosing the winners from everyone who has subscribed to the Tuts+ Live Workshops newsletter, so no worries if you’ve already signed up. We’ll also reimburse any winners who have already paid for their ticket.

To enter simply subscribe to the Tuts+ Live Workshops newsletter and stay informed on upcoming workshops!

Cargo-Culting in JavaScript

James Padolsey — Fri, 24 May 2013 15:04:57 +0000

Cargo-cult programming is what a programmer does when he or she doesn't know a particular language or paradigm well enough, and so ends up writing redundant and possibly harmful code. It rears its head quite often in the land of JavaScript. In this article, I explore the concept of cargo-cult programming and places to watch out for it in JavaScript.

Dogmatic rules surface and spread, until they are considered the norm.

Cargo-culting is sometimes defined as "the extreme adherence to the form instead of content." The form, in programming, being the syntax, paradigms, styles and patterns that we employ. The content being the abstract thing that you are seeking to represent through your code — the very substance of your program. A person with lacking understanding in an area is likely to copy the form of others without truly understanding, and thus their content — their program — can suffer.

Cargo-culting is curiously common in JavaScript, probably because of the general low barrier to entry in the front-end development world. You can whip up an HTML page with a bit of JavaScript in seconds. As a result, there are many people who become sufficiently proficient in these technologies to feel comfortable creating and imposing rules on themselves and others. Eventually, other newcomers copy these rules. Dogmatic rules surface and spread, until they are considered the norm:

Always use strict equality operators
Never use eval
Always use a single var declaration per scope
Always use an IIFE – it “protects” you

A rule continues to spread until a programmer is only using a given technique because of its popularity, instead of considering each specific use-case independently.

JavaScript Abuzz with Semi-colons

If you've had the opportunity to witness the witty banter and rhetoric of the software developer over the years, you will have spotted a tendency to discuss seemingly tiny things at great lengths. Things like the semi-colon, the comma, white-space or the curly brace.

Syntax like semi-colons or white-space may seem to purely be elements of form, not of content. But many of these subtle syntax rules can have significant effects in JavaScript. If you don't understand the 'form' then you cannot begin to understand the 'content'.

So in this article, we will identify what areas of form in JavaScript are frequently cargo-culted off of — that is, copied without understanding.

How JavaScript can seem… an image from Angus Croll’s "The Politics Of JavaScript" presentation

Undefined

Angus Croll, in a recent presentation, titled "The Politics Of JavaScript", highlighted one of the most common pieces of JS dogma that people cargo-cult off of:

if (typeof myObject.foo === 'undefined') {...}

Most of the time, doing such a long-winded check for undefined is pointless. The technique became common because people were copying other people, not because of it's actual value.

Of course, there are times when:

typeof x === 'undefined'

… is preferable to:

x === undefined

But, equally, there are times when the latter is preferred. A quick overview of the options:

// Determine if `x` is undefined:
x === undefined
typeof x == 'undefined'
typeof x === 'undefined'
x === void 0

// Determine if `x` is undefined OR null:
x == null
x == undefined

People started using the typeof approach because they were protecting themselves against:

A potentially undeclared variable (non-typeof approaches would throw TypeErrors)
Someone overwrote undefined globally or in a parent scope. Some environments allow you to overwrite undefined to something like true. You have to ask yourself: “Is it likely that someone overwrote undefined, and should my script have to pander to such silliness?“

But most of the time they're protecting themselves from having to worry. It's a catch-all avoidance of having to know the details. Knowing the details can help you though. Every character of your code should exist with a purpose in mind.

The only time that you should need to use a typeof check for undefined is when you are checking for a variable that may not have been declared, e.g. checking for jQuery in the global scope:

if (typeof jQuery != 'undefined') {
    // ... Use jQuery
}

The thing is, if jQuery does exist, then we can be sure that it's an object – a "truthy" thing. So this would be sufficient:

// or:
if (window.jQuery) {

}

The Great Strict/non-strict Debate

Let's take something very common and generally considered good advice, solely using strict-equality:

a === b

Strict-equality is said to be good because it avoids ambiguity. It checks both the value and the type, meaning that we don't have to worry about implicit coercion. With non-strict equality, we do have to worry about it though:

1 == 1    // true &mdash; okay, that's good
1 == "1"  // true &mdash; hmm
1 == [1]  // true &mdash; wat!?

So it would seem sensible advice to entirely avoid non-strict equality, right? Actually, no. There are many situations where strict-equality creates large amounts of redundancy, and non-strict equality is preferable.

When you know, with 100% certainty, that the types of both operands are the same, you can avoid the need for strict-equality. For example, I always know that the typeof operator returns a string, and my right-hand operand is also a string (e.g. "number"):

// With strict-equals
typeof x === 'number'

// With non-strict-equals:
typeof x == 'number'

They're both effectively identical. I am not necessarily suggesting that we abandon strict-equals in this case — I am suggesting that we remain aware of what we're doing so that we can make the best choices given each situation.

Another quite useful example is when you want to know if a value is either null or undefined. With strict equality, you might do this:

if (value === undefined || value === null) {
    // ...
}

With non-strict equality, it's far simpler:

if (value == null) {
    // ...
}

There is no catch here — it is doing exactly what we want, only, arguably, less visibly. But, if we know the language, then what's the problem? It's right there in the spec:

The comparison x == y, where x and y are values, produces true or false. Such a comparison is performed as follows:

If x is null and y is undefined, return true.
If x is undefined and y is null, return true.

If you're writing JavaScript with the intention of it being read, if at all, by people that know JavaScript, then I would argue that you shouldn't feel bad taking advantage of implicit language rules, like this.

`hasOwnProperty`

The hasOwnProperty method is used to determine whether a property is directly owned by an object. Is it commonly found in for..in loops to ensure that you only mess with direct properties and not inherited properties.

for (var i in object) {
    if (object.hasOwnProperty(i)) {
        // We can do stuff with `object[i]`
    }
}

It’s important to note that the for-in statement will only loop through enumarable properties. Native inherited methods, for example, are not enumerable and so you don't need to worry about them anyway.

The hasOwnProperty check is specifically preventing you from touching properties that you or some third-party script has defined, i.e. when your object's prototype has enumerable properties.

If you know that your object's prototype (or its prototype’s prototype etc.) doesn't have any enumerable properties, then you don't have to worry about using hasOwnProperty in your for-in loops. And, if your object is initialized, via ES5's Object.create(null), then you won't even be able to call hasOwnProperty directly on the object (no prototype means no inherited native methods). This means that using hasOwnProperty by default in all of your for-in loops may actually break sometimes.

One potential solution for objects with null prototypes is to use a saved reference to hasOwnProperty, like so:

var hasOwnProperty = Object.prototype.hasOwnProperty;

// Later in your code:
for (var i in someObject) {
    if (hasOwnProperty.call(someObject, i)) {
        // ...
    }
}

That will work even if the object has no prototype (in the case of Object.create(null)). But, of course, we should only do this in the first place if we know we need it. If you're writing a third-party script for a "hostile" environment, then yes, definitely check for enumerable inherited properties. Otherwise, it may not be necessary all the time.

Note: IE9 and Safari 2.0 complicate the matter further when you're trying to identify enumerable properties that are already defined as non-enumerable. It's worth checking out a truly cross-browser forOwn loop implementation.

To conclude: your use of hasOwnProperty should depend on the object being looped over. It depends on what assumptions you can safely make. Blindly protecting yourself using the hasOwnProperty will not suffice in all cases. Be wary of cross-browser differences too.

Over-Parenthesising

Another common redundancy that creeps into JS code is the parenthesis. Within expressions, it is used to force specific grouping of sub-expressions. Without them, you are at the mercy of operator precedences and associativities. For example:

A && B || C
A && (B || C)
(A && B) || C

One of those is not like the other. The parentheses force a specific grouping, and many people prefer the extra clarity. In this case, the logical AND operator has a higher precedence than the logical OR operator, meaning that it is the first and last lines that are equivelant. The second line is an entirely different logical operation.

Higher precedence means that it will occur before other operations in a series of operations.

To avoid this complexity, developers frequently opt for a "parentheses policy" — where you keep adding parentheses until it is abundantly clear which operations are occurring, both for you and potential readers of the code. It can be argued that this verbosity ends up making things less clear though.

It’s tricky for a reader sometimes. One must consider that any given parentheses may have been added because:

It was needed to override default precedence/associativity
For no functional reason at all, just for "protection" or "clarity"

Take this example:

A && B ? doFoo() : doBaz()

Without knowledge of operator precedence rules, we can see two possible operations here:

(A && B) ? doFoo() : doBaz()
A && (B ? doFoo() : doBaz())

In this case, it's the logical AND that has the higher precedence, meaning that the equivalent parenthesised expression is:

(A && B) ? doFoo() : doBaz()

We should feel no obligation to add these parentheses in our code, though. It happens implicitly. Once we recognize that it happens implicitly, we are free to ignore it and focus on the program itself.

There are, of course, valid arguments to retain the parentheses where implicit grouping is unclear. This really comes down to you and what you're comfortable with. I would, however, implore you to learn the precedences and then you can be fully empowered to take the best route, dependent on the specific code you're dealing with.

Object Keys

It's not rare to see redundant quotes in object literals:

var data = {
  'date': '2011-01-01',
  'id': 3243,
  'action': 'UPDATE',
  'related': { '1253': 2, '3411': 3 }
};

In addition to strings, JavaScript allows you to use valid identifier names and numbers as object literal keys, so the above could be re-written to:

var data = {
  date: '2011-01-01',
  id: 3243,
  action: 'UPDATE',
  related: { 1253: 2, 3411: 3 }
};

Sometimes, you may prefer the added consistency of being able to use quotes, especially if a field-name happens to be a reserved word in JavaScript (like 'class' or 'instanceof'). And that's fine.

Using quotes is not a bad thing. But it is redundant. Knowing that you don't have to use them is half the battle won. It is now your choice to do what you want.

Comma Placement

There is a huge amount of subjective preference, when it comes to punctuation placement in programming. Most recently, the JavaScript world has been abuzz with rhetoric and discontent over the comma.

Initialising an object in traditionally idiomatic JavaScript looks like this:

var obj = {
    a: 1,
    b: 2,
    c: 3
};

There is an alternative approach, which has been gaining momentum though:

var obj = {
      a: 1
    , b: 2
    , c: 3 
};

The supposed benefit of placing the commas before each key-value pair (apart from the first) is that it means you only have to touch one line in order to remove a property. Using the traditional approach, you would need to remove "c: 3" and then the trailing comma on the line above. But with the comma-first approach you're able to just remove ", c: 3". Proponents claim this makes trailing commas less likely and also cleans up source-control diffs.

Opponents, however, say that this approach only achieves getting rid of the trailing-comma "problem" by introducing a new leading-comma problem. Try removing the first line and you're left with a leading comma on the next line. This is actually considered a good thing by comma-first proponents, because a leading comma would immediately throw a SyntaxError. A trailing comma, however, throws nothing, except in IE6 and 7. So if the developer fails to test their JS in those versions of IE, then the trailing commas can often creep into production code, which is never good. A leading comma throws in all environments, so is less likely to be missed.

Of course, you might argue that this entire thing is moot. We should probably be using linters like JSLint or the kinder JSHint. Then we're free to use the punctuation and whitespace placement that makes the most sense to us and our coworkers.

Let's not even get started on the comma-first style in variable declarations..

var a = 1
  , b = 2
  , c = 3
  ;

Thou Shalt Code for Psychopaths?

We should endeavour to learn the languages we use to a good enough level that we're able to avoid cargo-culting and over-protective catch-all coding techniques. And we should trust our coworkers and other developers to do the same.

We’ve also discussed the abandonement of cruft in favor of taking advantage of a language’s idiosyncracies and implicit rules. To some, this creates maintainability issues, especially if someone more junior in their acquisition of a given language approaches the code. For example, what if they don’t know about JavaScript’s weak vs. strict equality?

On the topic of maintainability, we’re reminded by this famous quote:

Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.

I don’t know if that is truly good advice. Even taken metaphorically, it suggests a distrust of the fictional maintainer’s competency — and the need to worry about their understanding above everything else. I would rather write code in the knowledge that it will be taken care of by people that know their stuff. So as a possible contradiction or even an addendum to that quote, I offer:

Always code as if the person who ends up maintaing your code is knowledgeable about the language and its constructs and is seeking to gain understanding of the problem domain through reading your code.

While this may not always be true, we should seek for it be so. We should endeavour to ensure that people working on a specific technology have the sufficient understanding to do so. The learned cargo-culter says:

If I forever pander to a lower level of understanding in my code — treading softly — strictly abiding to conventions and style guides and things I see the “experts” do, then I am never able to advance my own understanding, nor take advantage of a language in all its weirdness and beauty. I am happily and blissfully settled in this world of rules and absolutes, but to move forward, I must exit this world and embrace higher understanding.

Laravel 4: A Start at a RESTful API (Updated)

Chris Fidao — Wed, 22 May 2013 16:00:07 +0000

RESTful API's are hard! There are a lot of aspects to designing and writing a successful one. For instance, some of the topics that you may find yourself handling include authentication, hypermedia/HATEOS, versioning, rate limits, and content negotiation. Rather than tackling all of these concepts, however, let's instead focus on the basics of REST. We'll make some JSON endpoints behind a basic authentication system, and learn a few Laravel 4 tricks in the process.

The App

Let's build an API for a simple Read-It-Later app. Users will be able to create, read, update and delete URLs that they wish to read later.
Ready to dive in and get started?

Install Laravel 4

Create a new install of Laravel 4. If you're handy with CLI, try this quickstart guide. Otherwise, we have a video tutorial here on Nettuts+ that covers the process.

We're going to first create an encryption key for secure password hashing. You can do this easily by running this command from your project root:

$ php artisan key:generate

Alternatively, you can simple edit your app/config/app.php encryption key:

/*
|--------------------------------------------------------------------------
| Encryption Key
|--------------------------------------------------------------------------
|
| This key is used by the Illuminate encrypter service and should be set
| to a random, long string, otherwise these encrypted values will not
| be safe. Make sure to change it before deploying any application!
|
*/

'key' => md5('this is one way to get an encryption key set'),

Database

Once you have a working install of Laravel 4, we can get started with the fun. We'll begin by creating the app's database.

This will only require two database tables:

Users, including a username and password
URLs, including a url and description

We'll use Laravel's migrations to create and populate the database.

Configure Your Database

Edit app/config/database.php and fill it with your database settings. Note: this means creating a database for this application to use. This article assumes a MySQL database.

'connections' => array(

    'mysql' => array(
        'driver'    => 'mysql',
        'host'      => 'localhost',
        'database'  => 'read_it_later',
        'username'  => 'your_username',
        'password'  => 'your_password',
        'charset'   => 'utf8',
        'collation' => 'utf8_unicode_ci',
        'prefix'    => '',
    ),
),

Create Migration Files

$ php artisan migrate:make create_users_table --table=users --create
$ php artisan migrate:make create_urls_table --table=urls --create

These commands set up the basic migration scripts that we'll be using to create the database tables. Our job now is to fill them with the correct table columns.

Edit app/database/migrations/SOME_DATE_create_users_table.php and add to the up() method:

public function up()
{
    Schema::create('users', function(Blueprint $table)
    {
        $table->increments('id');
        $table->string('username')->unique();
        $table->string('password');
        $table->timestamps();
    });
}

Above, we're setting a username (which should be unique), a password, as well as the timestamps. Save that, and now edit app/database/migrations/SOME_DATE_create_urls_table.php, and add to the up() method:

public function up()
{
    Schema::create('urls', function(Blueprint $table)
    {
        $table->increments('id');
        $table->integer('user_id');
        $table->string('url');
        $table->string('description');
        $table->timestamps();
    });
}

The only important note in this snippet is that we're creating a link between the url and users table, via the user_id field.

Add Sample Users

We can use Laravel's seeds to create a few sample users.

Create a file within the app/database/seeds folder that has the same name as the table that it corresponds to; in our case, UserTableSeeder.php. Add:

<?php

class UserTableSeeder extends Seeder {

    public function run()
    {
        DB::table('users')->delete();

        User::create(array(
            'username' => 'firstuser',
            'password' => Hash::make('first_password')
        ));

        User::create(array(
            'username' => 'seconduser',
            'password' => Hash::make('second_password')
        ));
    }

}

Next, make sure that seeder class gets run when the database is seeded. Edit app/database/seeds/DatabaseSeeder.php:

public function run()
{
    Eloquent::unguard();

    // Add or Uncomment this line
    $this->call('UserTableSeeder');
}

Run the Migrations

Here’s how to create those two tables, and insert our sample users.

// Create the two tables
$ php artisan migrate

// Create the sample users
$ php artisan db:seed

Models

Laravel 4 continues to use the excellent Eloquent ORM. This will make the process of handling database calls a snap. We'll require one model per table.

Luckily, Laravel comes with a User model setup, so let's create a model for our urls table.

Create and edit file app/models/Url.php.

<?php

class Url extends Eloquent {

    protected $table = 'urls';

}

Authentication

Laravel's filters can handle authentication for us. In particular, Laravel now comes with a Basic Authentication filter, which we can use as a quick authentication model to be used with our API requests.

If you open app/filters.php, you'll see what it looks like:

Route::filter('auth.basic', function()
{
    return Auth::basic();
});

We just need to make one adjustment. By default, this filter looks for an "email" field to identify the user. Since we're using usernames instead of emails, we just need to adjust that preference. Change the Auth::basic() call by giving it our username field as a parameter:

Route::filter('auth.basic', function()
{
    return Auth::basic("username");
});

Routes

Let's test this out. Create a route, called testauth, and make sure that our auth.basic filter runs before it.

Edit app/routes.php:

Route::get('/authtest', array('before' => 'auth.basic', function()
{
    return View::make('hello');
}));

We can test this with a curl request. From your terminal, try pointing to your build of Laravel. In mine, it looks like this (Your URL will likely be different!):

$ curl -i localhost/l4api/public/index.php/authtest
HTTP/1.1 401 Unauthorized
Date: Tue, 21 May 2013 18:47:59 GMT
WWW-Authenticate: Basic
Vary: Accept-Encoding
Content-Type: text/html; charset=UTF-8

Invalid credentials

As you can see, an unauthorized request is detected and a "Invalid Credentials" message is returned with a 401 status code. Next, try including basic authentication.

$ curl --user firstuser:first_password localhost/l4api/public/index.php/authtest
HTTP/1.1 200 OK
Date: Tue, 21 May 2013 18:50:51 GMT
Vary: Accept-Encoding
Content-Type: text/html; charset=UTF-8

<h1>Hello World!</h1>

It worked!

At this point, the baseline work of our API is done. We have:

Installed Laravel 4
Created our database
Created our models
Created an authentication model

Creating Functional Requests

You may be familiar with Laravel's RESTful controllers. They still exist in Laravel 4; however, we can also use Laravel's Resourceful Controllers, which set up some paradigms that we can use to make a consistent API interface. We'll be using a Resourceful controller.

Here's a breakdown of what each method in the resourceful controller will handle. Please note that you can remove the /resource/create and /resource/{id}/edit routes, since we won't be needing to show 'create' or 'edit' forms in an API.

Create a Resourceful Controller

$ php artisan controller:make UrlController

Next, setup a route to use the controller, and require each route to be authenticated.

Edit app/routes.php and add:

// Route group for API versioning
Route::group(array('prefix' => 'api/v1', 'before' => 'auth.basic'), function()
{
    Route::resource('url', 'UrlController');
});

A few things are happening there.

This is going to respond to requests made to http://example.com/api/v1/url.
This allows us to add extra routes, if we need to expand our API. For instance, if you add a user end-point, such as /api/v1/user.
There is also a naming mechanism in place for versioning our API. This gives us the opportunity to roll out new API versions without breaking older versions – We can simply create a v2 route group, and point it to a new controller!

Note: You may want to consider more advanced API versioning techniques, such as using an Accept header or subdomain which can help you point different API versions separate code bases.

Add the Functionality

Edit the new app/controllers/UrlController.php file:

// Edit this:
public function index()
{
    return 'Hello, API';
}

Let’s test it:

$ curl -i localhost/l4api/public/index.php/api/v1/url
HTTP/1.1 401 Unauthorized
Date: Tue, 21 May 2013 19:02:59 GMT
WWW-Authenticate: Basic
Vary: Accept-Encoding
Content-Type: text/html; charset=UTF-8

Invalid credentials.

$ curl --user firstuser:first_password localhost/l4api/public/index.php/api/v1/url
HTTP/1.1 200 OK
Date: Tue, 21 May 2013 19:04:19 GMT
Vary: Accept-Encoding
Content-Type: text/html; charset=UTF-8

Hello, API

We now have a resourceful controller with authentication working, and are ready to add functionality.

Create a URL

Edit app/controllers/UrlController.php:

/**
 * Store a newly created resource in storage.
 *
 * @return Response
 */
public function store()
{
    $url = new Url;
    $url->url = Request::get('url');
    $url->description = Request::get('description');
    $url->user_id = Auth::user()->id;

    // Validation and Filtering is sorely needed!!
    // Seriously, I'm a bad person for leaving that out.

    $url->save();

    return Response::json(array(
        'error' => false,
        'urls' => $urls->toArray()),
        200
    );
}

It's time to test this with another curl request. This one will send a POST request, which will correspond to the store() method created above.

$ curl -i --user firstuser:first_password -d 'url=http://google.com&description=A Search Engine' localhost/l4api/public/index.php/api/v1/url
HTTP/1.1 201 Created
Date: Tue, 21 May 2013 19:10:52 GMT
Content-Type: application/json

{"error":false,"message":"URL created"}

Cool! Let's create a few more, for both of our users.

$ curl --user firstuser:first_password -d 'url=http://fideloper.com&description=A Great Blog' localhost/l4api/public/index.php/api/v1/url

$ curl --user seconduser:second_password -d 'url=http://digitalsurgeons.com&description=A Marketing Agency' localhost/l4api/public/index.php/api/v1/url

$ curl --user seconduser:second_password -d 'url=http://www.poppstrong.com/&description=I feel for him' localhost/l4api/public/index.php/api/v1/url

Next, let's create methods for retrieving URLs.

/**
 * Display a listing of the resource.
 *
 * @return Response
 */
public function index()
{
    //Formerly: return 'Hello, API';

    $urls = Url::where('user_id', Auth::user()->id)->get();

    return Response::json(array(
        'error' => false,
        'urls' => $urls->toArray()),
        200
    );
}

/**
 * Display the specified resource.
 *
 * @param  int  $id
 * @return Response
 */
public function show($id)
{
    // Make sure current user owns the requested resource
    $url = Url::where('user_id', Auth::user()->id)
            ->where('id', $id)
            ->take(1)
            ->get();

    return Response::json(array(
        'error' => false,
        'urls' => $url->toArray()),
        200
    );
}

Let's test them out:

$ curl --user firstuser:first_password localhost/l4api/public/index.php/api/v1/url
{
    "error": false,
    "urls": [
       {
            "created_at": "2013-02-01 02:39:10",
            "description": "A Search Engine",
            "id": "2",
            "updated_at": "2013-02-01 02:39:10",
            "url": "http://google.com",
            "user_id": "1"
        },
        {
            "created_at": "2013-02-01 02:44:34",
            "description": "A Great Blog",
            "id": "3",
            "updated_at": "2013-02-01 02:44:34",
            "url": "http://fideloper.com",
            "user_id": "1"
        }
    ]
}

$ curl --user firstuser:first_password localhost/l4api/public/index.php/api/v1/url/1
{
    "error": false,
    "urls": [
        {
            "created_at": "2013-02-01 02:39:10",
            "description": "A Search Engine",
            "id": "2",
            "updated_at": "2013-02-01 02:39:10",
            "url": "http://google.com",
            "user_id": "1"
        }
    ]
}

Almost done. Let's now allow users to delete a url.

/**
 * Remove the specified resource from storage.
 *
 * @param  int  $id
 * @return Response
 */
public function destroy($id)
{
    $url = Url::where('user_id', Auth::user()->id)->find($id);

    $url->delete();

    return Response::json(array(
        'error' => false,
        'message' => 'url deleted'),
        200
        );
}

Now, we can delete a URL by using a DELETE request:

$ curl -i -X DELETE --user firstuser:first_password localhost/l4api/public/index.php/api/v1/url/1
HTTP/1.1 200 OK
Date: Tue, 21 May 2013 19:24:19 GMT
Content-Type: application/json

{"error":false,"message":"url deleted"}

Lastly, let's allow users to update a url.

/**
 * Update the specified resource in storage.
 *
 * @param  int  $id
 * @return Response
 */
public function update($id)
{
    $url = Url::where('user_id', Auth::user()->id)->find($id);

    if ( Request::get('url') )
    {
        $url->url = Request::get('url');
    }

    if ( Request::get('description') )
    {
        $url->description = Request::get('description');
    }

    $url->save();

    return Response::json(array(
        'error' => false,
        'message' => 'url updated'),
        200
    );
}

To test URL updates, run:

$ curl -i -X PUT --user seconduser:second_password -d 'url=http://yahoo.com' localhost/l4api/public/index.php/api/v1/url/4
HTTP/1.1 200 OK
Date: Tue, 21 May 2013 19:34:21 GMT
Content-Type: application/json

{"error":false,"message":"url updated"}

// View our changes
$ curl --user seconduser:second_password localhost/l4api/public/index.php/api/v1/url/4
{
    "error": false,
    "urls": [
        {
            "created_at": "2013-02-01 02:44:34",
            "description": "I feel for him",
            "id": "3",
            "updated_at": "2013-02-02 18:44:18",
            "url": "http://yahoo.com",
            "user_id": "1"
        }
    ]
}

And That’s It

We now have the beginnings of a fully-functioning API. I hope that you've learned a lot about how to get an API underway with Laravel 4.

To recap, we achieved the following in this lesson:

Install Laravel
Create the database, using migrations and seeding
Use Eloquent ORM models
Authenticate with Basic Auth
Set up Routes, including versioning the API
Create the API functionality using Resourceful Controllers

The Next Steps

If you’d like to push your API up a notch, you might consider any of the following as a next step.

Validation (Hint: Laravel has a Validation library).
API-request error handling – It's still possible to receive HTML response on API requests (Hint: Laravel Error Handling, plus Content Negotiation.)
Content Negotiation – listening for the Accept header. (Hint: Laravel's Request Class will give you the request headers).
Check out the API Craft Google Group
Learn about the different types caching and how Validation Caching can improve your API
Unit test your code
Check out Apigee's great API resources

The Right Way to Retinafy Your Websites

Allan Berger — Tue, 21 May 2013 14:55:30 +0000

Making your website ready for Retina display doesn’t have to be a hassle. Whether you are building a new website or upgrading an existing one, this guide is designed to help you get the job done smoothly.

Make it Retina First

The easiest and most time-saving way to add Retina support is to create one image that is optimized for Retina devices, and serve it to non-Retina devices as well.

By now, every modern browser uses bicubic resampling and does a great job with downsampling images. Here’s a comparison of downsampling in Photoshop vs. Google Chrome, using an image from our Growth Engineering 101 website.

There are two ways to let the browser downsample images for you: img tags or CSS background images.

You can have img tags serve the Retina-optimized image, and set the width and height attributes to half of the resolution of the actual image (e.g. 400×300 if the image dimensions are 800×600).

<img src="http://www.example.com/Retina-image-800x600-2x.png" width="400" height="300">

If you use images as CSS backgrounds, you may use the CSS3 background-size property to downsample the image for non-Retina devices.

<div class="photo"></div>

.photo {
    background-image: url(Retina-image-800x600-2x.png);
    background-size: 400px 300px;
    background-repeat: no-repeat;
    display: block;
    width: 400px;
    height: 300px;
}

In both cases, be sure to use even numbers in both dimensions to prevent displacement of pixels when the image is being downsampled by the browser.

When Downsampling is Not Good Enough

Usually, browser downsampling should work quite well. That said, there are some situations where downsampling in the browser might make images blurry.

Here we have a bunch of 32px social icons.

And here is how they will appear, when downsampled to 16px by Photoshop’s as well as Google Chrome’s bicubic filter. It seems that we get better results from Photoshop in this case.

To get the best results for our users, we can create two versions of the same image: one for Retina devices, and another one that has been downsampled by Photoshop for non-Retina devices.

Now, you can use CSS media queries to serve Retina or non-Retina images, dependent upon the pixel density of the device.

/* CSS for devices with normal screens */
.icons {
    background-image: url(icon-sprite.png);
    background-repeat: no-repeat;
}

/* CSS for high-resolution devices */
@media only screen and (-Webkit-min-device-pixel-ratio: 1.5),
only screen and (-moz-min-device-pixel-ratio: 1.5),
only screen and (-o-min-device-pixel-ratio: 3/2),
only screen and (min-device-pixel-ratio: 1.5) {
    .icons {
        background-image: url(icon-sprite-2x.png);
        background-size: 200px 100px;
        background-repeat: no-repeat;
    }
}

If you use a background color for small icons, on the other hand, downsampling by the browser works rather well. Here is the same downsampling example with a white background.

Polishing Your Downsampled Images

If you’re still not satisfied with the results from Photoshop’s downsampling, you can go the extra mile and hand-optimize the non-Retina version to get super crisp results.

Below are some examples of images from the Blossom product website that I hand-optimized for those who are still on non-Retina devices.

Borders and Strokes

Here’s an example of downsampling issues with hairlines, where I re-draw the lines of the downsampled image.

View the Retina Version of this Image on Dribbble.

Text

Next, we come to an example of downsampling issues with text. In this case, I manually re-wrote the text “Feature Pipeline” to make the result as crisp as possible.

Retina Version

When details, crisp fonts, and clean hairlines are important, you might want to go the extra mile.

Try to Avoid Images

The main disadvantages of rasterized images are their considerable file size and that they don’t scale well to different sizes without affecting the image quality. Great alternatives to rasterized graphics are CSS, Scalable Vector Graphics (SVG), and Icon Fonts.

If you have any chance to build the graphical elements for your website in CSS, go for it. It can be used to add gradients, borders, rounded corners, shadows, arrows, rotate elements and much more.

Here are a few examples of interaction elements in Blossom that are implemented in CSS. The subtle gradient is powered by CSS gradients, and the custom font in use on this button is Kievit, served via Typekit. No images.

In the following screenshot, the only two images used are the user avatar and the blue stamp. Everything else – the circled question mark, the dark grey arrow next to it, the popover, its shadow and the arrow on top of it – is pure HTML and CSS.

Here, you can see how projects in Blossom appear. It’s a screenshot of a project’s website used as cover on a stack of paper sheets. The paper sheets are implemented with divs that are rotated using CSS.

Also, the circled arrow in the right-hand side of the screenshot below is pure CSS.

Tools

Here are some awesome tools that will help save time when creating effects with CSS.

CSS Generator: Cross browser CSS3 syntax by @RandyJensen.
CSS Arrows: CSS for tooltip arrows by @ShojBerg.
Generating CSS for Sprites: Sprite Cow helps you get the background-position, width and height of sprites within a spritesheet as a nice bit of copyable css. It’s built by TheTeam, and is a real time saver – definitely worth a try.

The primary advantage to SVG is that, unlike rasterized graphics, they scale reasonably well to various sizes. If you’re working with simple shapes, they typically are smaller than PNGs. Often, they are used for things like charts.

Icon Fonts are frequently used as a replacement for image sprites. Similar to SVG, they can be scaled up infinitely without any loss of quality and are usually smaller in size, when compared to image sprites. On top of that, you can use CSS to change their size, color and even add effects, such as shadows.

Both SVG and Icon Fonts are well supported by modern browsers.

Retina-Ready Favicons

Favicons are really important for users who need an easy way to remember which website belongs to which browser tab. A Retina-ready Favicon will not only be easier to identify, but it will also stand out among a crowd of pixelated Favicons that haven’t yet been optimized.

To make your Favicon Retina-ready, I highly recommend X-Icon Editor. You can either upload a single image and let the editor resize it for different dimensions, or you can upload separate images optimized for each size to get the best results.

How to Make Existing Images Retina-Ready

If you want to upgrade a website with existing images, a bit more work is required, as you’ll need to re-create all images to make them Retina-ready, but this doesn’t have to waste too much time.

First, attempt to identify images that you can avoid by using alternatives like CSS, SVG and Image Fonts, as noted previously. Buttons, Icons and other common UI widgets usually can be replaced with modern solutions that don’t require any images.

In case you actually need to re-create rasterized images, you’ll of course want to return to the source files. As you might assume, simply resizing your rasterized bitmap images to be twice as big doesn’t get the job done, because all of the details and borders will become pixelated.

No need to despair – image compositions which mostly contain vectors (i.e. in Adobe Photoshop or Illustrator) are quite easy to scale up. That said, don’t forget to verify if your Photoshop effects in the blending options, such as strokes, shadows and bevels, still appear as you intended.

In general, making Photoshop compositions directly out of vectors (shapes) and Photoshop’s Smart Objects will save you a great deal of time in the future.

How to Optimize the File Size of Images

Last, but not least, optimizing the file size of all images in an application or website could effectively save up to 90% of image loading times. When it comes to Retina images, the file size reduction gets even more important, as they have a higher pixel density that will increase their respective file sizes.

In Photoshop, you can optimize the image file size, via the “Save for Web” feature. On top of that, there is an excellent free tool, called ImageAlpha, which can reduce the size of your images even more with just a minor loss of quality.

Unlike Photoshop, ImageApha can convert 24-bit alpha channel PNGs to 8-bit PNGs with alpha channel support. The icing on the cake is that these optimized images are cross-browser compatible and even work for IE6!

You can play around with different settings in ImageAlpha to get the right trade-off between quality and file size. In the case below, we can reduce the file size by nearly 80%.

When you’re finished setting your desired compression levels, ImageAlpha’s save dialog also offers to “Optimize with ImageOptim” – another great and free tool.

ImageOptim automatically picks the best compression options for your image and removes unnecessary meta information and color profiles. In the case of our stamp file, ImageOptim was able to reduce the file size by another 34%.

After we updated all assets at Blossom.io for high resolution displays and used ImageAlpha and ImageOptim to optimize the file size, we actually ended up saving a few kilobytes in comparison to the assets we had before.

Save Time, Read This Book

If you want to learn more about how to get your apps and websites ready for Retina displays, I highly recommend “Retinafy your web sites & apps”, by Thomas Fuchs. It’s a straight-forward step by step guide that saved me a lot of time and nerves.

Awesome Retina-Ready Sites on the Web

http://kickoffapp.com/

http://www.layervault.com

http://www.apple.com

http://www.panic.com

Thanks for reading! Any questions?

How to Create a PyroCMS Theme

Zac Vineyard — Mon, 20 May 2013 16:00:33 +0000

Like most content management systems, PyroCMS uses front-end themes. Though PyroCMS themes are built a bit differently than what you might be used to from other systems, they’re still quite easy to create. They’re so easy, in fact, that very little PHP experience is required to assemble them!

The Folder Structure

PyroCMS themes consist of HTML, images, CSS, and JavaScript, arranged into the following supported folders:

css
img
js
views
views/layouts
views/partials
views/modules

While these folders will no doubt look familiar to you, the "views" folder makes the most sense within the context of MVC. When building a theme for PyroCMS, you are really building the views (including assets) of a MVC patterned application. These views consist of a master layout file and multiple partial files (i.e. a header.html or footer.html) that shares presentation logic between different layouts. We’ll discuss this more shortly.

Getting Started

To get started building your first PyroCMS theme, create the supported folder structure in one of the two places that themes may reside within an instance of PyroCMS:

addons/shared_addons/themes (for themes available to all sites)

Or:

addons/[site-name]/themes (for themes available to only one specific site)

Once you have the base theme folder containing the supported folder structure created, the first file that you'll want to add to your theme is theme.php.

addons/shared_addons/themes/[my-theme-name]/theme.php

This theme.php file contains all essential details for your theme, including its name, author, version, etc. In a way, this file is similar to the comment block found at the top of a WordPress theme's style.css file. Here’s a basic example of a theme.php file for your PyroCMS theme:

<?php defined('BASEPATH') OR exit('No direct script access allowed');

class Theme_Foo extends Theme
{
    public $name = 'Foo';
    public $author = 'Zac Vineyard';
    public $author_website = 'http://zacvineyard.com';
    public $website = 'http://example.com/themes/foo';
    public $description = 'The antithesis theme to your Bar theme.';
    public $version = '1.0';
}

 /* End of file theme.php */

Please take note that this file extends a PyroCMS class, called Theme. Also, because you are declaring a PHP class in this file, you'll need to make sure that the name of the folder containing your theme is used in the class declaration. So, if the folder housing your theme is called, "foo," the class created in your theme.php should be named, Theme_Foo (instead of Theme_Custom, as shown in the example within PyroCMS' documentation).

Once you have created your theme.php file, you can login to your PyroCMS control panel and view your theme listed in the Themes module.

Layouts

All layouts files for a PyroCMS theme exist in one of two locations:

addons/[site-ref]/themes/[my-theme-name]/views/layouts/

Or:

addons/shared_addons/themes/[my-theme-name]/views/layouts/

Every theme should have a layout file, named "default.html" in one of the locations listed above. Additional layout files are optional; I'll show you how to add more layout files in a moment. First, it’s important to review the contents of a layout file.

Layout files in PyroCMS are built using HTML and a tag parser, referred to as the Lex Tag Parser. This is what a very basic PyroCMS layout file looks like:

<!DOCTYPE html>
<html>
<head>
    <title>{{ template:title }}</title>
    {{ template:metadata }}
</head>
<body>
    <h1>{{ template:title }}</h1>
    {{ template:body }}
</body>
</html>

The special tags you see in this bit of HTML are Lex parser tags. If you've ever used Smarty templates in PHP, these may look somewhat familiar. The primary benefit to using Lex parser tags in your layout files is that you don't have to put PHP directly in your views (remember, we're using MVC), which gives you the best chance of creating PyroCMS themes that follow the don’t repeat yourself pattern.

The example that I've given above is simple, of course, but Lex parser tags are quite powerful. They can loop through data, work with attributes, and more. Learn more about the Lex Parser in the PyroCMS documentation.

A more complex PyroCMS layout file looks like this:

<!DOCTYPE html>
<html>
<head>
    <title>{{ template:title }}</title>
    {{ template:metadata }}
    {{ theme:favicon file="favicon.png" }}
    {{ theme:css file="style.css" }}
    {{ theme:js file="site.js" }}
</head>
<body>
    <div class="header">
        <div class="logo">
            {{ theme:image file="logo.jpg" alt="Your Cool Logo" }}
        </div>
        <div class="nav">
            {{ navigation:links group="header" }}
        </div>
    </div>
    <div class="content">
        <h1>{{ template:title }}</h1>
        {{ template:body }}
    </div>
</body>
</html>

You'll notice that this layout file, using Lex, includes assets, like CSS, JavaScript, and images. Using Lex tags and HTML allows PyroCMS developers to build layout files very quickly.

Partials

Partials in PyroCMS, which stands for partial layouts, allows you to break layouts into reusable parts or sections. These sections can then be loaded by different layout files. This keeps you from typing the same code (header, footer, etc.) into multiple layout files.

Depending on where you've placed your theme files, partials are created in one of two locations:

addons/[site-ref]/themes/[my-theme-name]/views/partials/

Or:

addons/shared_addons/themes/[my-theme-name]/views/partials/

Partials are loaded into layouts using this Lex tag:

{{ theme:partial name="partialname" }}

This Lex tag operates exactly like a PHP include statement – similar to one that you would find in WordPress or other themes. The code below is a simple example of a PyroCMS layout that takes advantage of partials.

{{ theme:partial name="header" }}

    <div class="content">
        <h1>{{ template:title }}</h1>
        {{ template:body }}
    </div>

{{ theme:partial name="footer" }}

The contents of the header.html partial and footer.html files are, of course, the HTML we'll need to reuse from the template in our previous code example above. One quick pointer: there is no limit to the number of partials that you can use in one layout. Additionally, partial files may contain any combination of valid HTML and Lex.

Multiple Layout Files

To add another layout to your instance of PyroCMS, create one more layout file in your theme's views/layouts/ directory. This file may receive any name, but it’s a good idea to name it as descriptively as possible – like about.html.

For added flexibility, you can make use of as many layout files as you'd like. When you edit or create a Page Type in your PyroCMS control panel (Control Panel→Pages→Page Types) and select your desired file from the dropdown, all the layouts in your theme's layout file will be available to use.

Mobile Layouts

PyroCMS is able to easily display separate layouts for mobile and desktops. To use this feature, move your layout files into a folder, called "web" within the views folder, so that your default layout will be located here:

[your-theme]/views/web/layouts/default.html

When a user accesses your site using a desktop browser, the primary layout files in this location will be used. If the user accesses your site using a mobile device browser, users will be supplied with the mobile layouts that you've created in this location:

[your-theme]/views/mobile/layouts/default.html

This feature works with multiple layout files.

Please take note of this warning found in the PyroCMS documentation: "PyroCMS does not consider the iPad a mobile device, so it will not load your mobile layouts if the user is accessing your site using an iPad." If, however, on your site, you'd like to make an iPad recognized as a mobile device, you can change the "user_agent.php" file within the config/ directory to make the iPad recognized a mobile device.

Finished!

Using this article as a guide, you can see how easy it is to create a theme in PyroCMS. The code examples provided are quite simple, so I encourage you to explore the PyroCMS documentation to become more experienced with layouts, mobile layouts, partials, and the Lex Parser in PyroCMS. Have fun!

The Linux Firewall

Patkos Csaba — Fri, 17 May 2013 18:00:48 +0000

There are several firewall applications for Linux, but what you may not realize is that, at the heart of all these programs is a single all-mighty application that is built right into the Linux Kernel: iptables. This is the Linux firewall. No matter which program you use to configure your firewall under Linux, it ultimately all comes down to iptables. All that these other programs do is configure it.

So, here comes the question: if those programs simply configure iptables, why not simply configure it directly yourself? Doing so is easier than you might think!

Networking Background

If you’re familiar with networking terms, like connections, IP, TCP, and Port, then feel free to skip ahead to the next step. Otherwise, if you’re new to networking, read on to familiarize yourself with the terms that you will need to understand, in order to follow along with this tutorial.

Please note that the terms and definitions below have been intentionally over-simplified. They’re meant for every-day users, not sysadmins. So if you are a seasoned sysadmin or you have a CCNA in you pocket, please excuse me for not entering into the details.

TCP/IP

TCP/IP is a protocol that allows computers to communicate with one another over Internet and Ethernet Networks.

Failure is the last resort.

Imagine an Ethernet Network as a small local network (LAN – local area network), like your home PC, laptop, and smart phone. It’s a small heterogeneous network that is isolated from the rest of the world. A network of such networks is what we all know as the Internet: a set of interconnected networks.

TCP/IP is a combination of two protocols working at different levels in the hierarchy of the network communication chain. We won’t delve into details about that hierarchy. TCP stands for Transfer Control Protocol, and its core responsibility is to ensure that communication is successful. It controls the correctness of the data sent, and ensures its success. It has different algorithms to perform sophisticated checksums, autocorrect, and retry. Failure is the last resort. The name, IP comes from Internet Protocol. You can best associate it with the “phone-number” of your PC. Each machine capable of communicating over the Internet must have an IP address – a unique phone number – so that communication packets can find their destinations. A packet is a small piece of data inside a communication stream, which is self contained and can be checked for correctness. Essentially, we can say that our computers send TCP packets over the Internet using the IP protocol.

Each network communication is bound to a specific port. Network ports range from 0 to 2^16 (65536). Each network connection has an outgoing port for the one who initiates it, and an inbound port for the one who is listening for other computers’ messages. There can be several connections between several computers over identical ports. A computer can, however, talk over several ports at once. So, basically, ports are good to identify services and define channels of communications, but they do not limit the amount of data or connections.

Some computers can have similar IP addresses. You may have observed that both your computer at home and at work have IP addresses that takes the form of something along the lines of 192.168.something.something, or 10.0.something.something, or 172.16.something.something. These are the so-called private IP addresses that can be used only inside your LAN. You can’t go out to the Internet with IP addresses like this. They are akin to interior numbers for your company’s phone network.

Gateway & Bridge

A Bridge is what computers with real (public) IP addresses pass to the Internet.

Essentially, these computers have the rights and capabilities to talk to one another on the Internet directly. But, since there are no direct connections between all the computers in the world (that would be quite hard to accomplish), bridges are responsible for connecting segments of the Internet.

Keeping our telephony analogy alive, you can imagine these bridges to be similar to the telephone centers in your town or neighborhood. If you make a call to another local number (the computers on the left in our schema), the communication could have been made directly by your telephone center by physically connecting your line with you neighbor’s. However, if you instead want to call your distant uncle Bob, your call would have to be redirected over several phone centers until your uncle’s phone could be connected. These form a bridge between your town and his town.

A Gateway is a way for computers from a private network (LAN with private IP addresses) to communicate with other computers on the Internet.

A private network is like your company’s private phone network. You can call interior numbers, but in order to call someone who is outside of your company’s network – like your wife at home – you must first dial a special number or prefix.

Computers actually function in a similar way. When you are on a private network, you have a so-called gateway computer. When your computer attempts to talk to another computer on the Internet, it will automagically contact the gateway first and request “a line” to the outside world. The gateway will do the talking to the computer found on the Internet, and will forward the message back to your computer. You, as an ordinary user, see no difference between a bridge and a gateway. Your computer will know how to deal with them.

Definition of a Firewall

A firewall is a program running on a Gateway, Bridge or PC/Laptop/Smartphone that is capable of filtering incoming, outgoing, and forwarded network packets. A firewall is essentially a tool that lets you restrict you or your network’s access to the Internet, and someone else’s access from the Internet to your network.

And yes, your cable router or home Wi-Fi is, in fact, a firewall for all your computers and gadgets that connect to the internet through it.

The Problem We Will Solve

To set the context, let’s imagine a very possible network architecture. I’ve seen many small companies running something similar to this.

What we have here is actually something quite simple:

A few computers and other network-connected devices – the green boxes
An e-mail server – the red box
A Microsoft Active Directory server – the blue box
A gateway, which is also a firewall, for our network running Linux – the black box
Between all of these is a simple network switch

In the following section, we will configure iptables on that gateway, so that it will allow all the devices in the network to connect to the Internet. It will allow us to connect to it, via SSH, and will allow external mail servers to reach the mail server inside our network – a computer that does not even have a public IP address; only a private one.

Iptables Components

Iptables’ name actually has a meaning in its functionality. It’s a set of tables of IP address and ports with some actions attached to them. In iptable’s terms, these tables are referred to as chains. An unconfigured, empty iptables might look like this:

csaba ~ # iptables -L
Chain INPUT (policy ACCEPT)
target     prot opt source               destination

Chain FORWARD (policy ACCEPT)
target     prot opt source               destination

Chain OUTPUT (policy ACCEPT)
target     prot opt source               destination

You can observe that there are three main chains:

INPUT – all incoming connections
FORWARD – connections passing through
OUTPUT – connections departing from this server

The term, “policy ACCEPT” in parenthesis means that ACCEPT is set as the default policy for that particular chain. So, when there is no match for a connection, that rule will be applied. There are three main concepts you can use when configuring your firewall:

default policy ACCEPT & deny selectively all you need to – it may be difficult to specify all that it is denied. I do not recommend this approach.
default policy DROP or REJECT & allow selectively all you need to – this is better, but it has a problem. If you make a mistake in your iptables configuration, you can easily remain with empty chains denying access to everything and everyone, including you. So, unless you always have physical access to your firewall server/computer, I recommend that you use the next approach.
default policy ACCEPT & an explicit policy to DROP all & then allow selectively all you need – this is a combined solution between the first two possibilities. It will use an ACCEPT default policy, so if something goes wrong, you can log back over SSH or whatever remote connection you use for your firewall. At the same time, an explicit DROP rule for any unmatched connections ensures that you are safe. Allowing only what you know about and actually need to use offers the best possible protection.

Adding Rules to Iptables

There are two ways to add a new rule to iptables. One is to insert it at the begining of a chain. The other option is to append it to the end of a chain. Why does it matter in which order the rules occur?

Important: iptables check the rules in a chain from top to bottom. It will stop its search at the first match.

You must design your rules in such a way to consider the above mentioned behavior of iptables. After the first match of a rule, iptables will take the actions specified by the rule, and then cease the search. If no rule matches the connection that is checked, the default policy applies.

Inserting a New Rule

Let’s say that we want to add a rule to our iptables that will allow anyone to connect to port 22 on our firewall. Port 22 is the port for the SSH protocol. Of course, a good server admin will change this port to something unexpected for obvious security/obscurity reasons, but that’s another story for another tutorial. We will stick with 22.

csaba ~ # iptables -I INPUT -i eth0 -p tcp --dport 22 -j ACCEPT
csaba ~ # iptables -L
Chain INPUT (policy ACCEPT)
target     prot opt source               destination
ACCEPT     tcp  --  anywhere             anywhere             tcp dpt:ssh

I presumed that the IP address facing the Internet with the public IP on it is on the network interface, called eth0. Let’s dissect this command:

-I – stands for insert the rule
INPUT – specifies the desired chain
-i – stands for network interface – in our case, eth0
-p – is for protocol (tcp or udp)
–dport 22 – is for destination port 22 – it has a corresponding --sport version for source port verification
-j – actually comes from “jump,” and is followed by an action -in our case, the action to accept the connection

However, you may have already guessed that this rule has little effect at this time. Our default policy is ACCEPT, so accepting something explicitly does not offer us any extra functionality. Now, remember the third recommended way to set up our firewall: the explicit rule to deny everything not matched. Let’s add that rule.

Appending Rules

We want to append a rule that blocks incoming traffic. But be careful: we only want to block what could be harmful. If we block everything, we will not be able to do anything, because the replies to our requests will be rejected. For example, when you browse a web page, you make a request, then you receive an answer. This answer comes into your computer, so, on the INPUT chain, we must have a rule to allow it.

First, we will append a rule to accept incoming traffic for already established connections, such as responses to requests.

csaba ~ # iptables -A INPUT -i eth0 -m conntrack  --ctstate ESTABLISHED,RELATED -j ACCEPT
csaba ~ # iptables -L
Chain INPUT (policy ACCEPT)
target     prot opt source               destination
ACCEPT     tcp  --  anywhere             anywhere             tcp dpt:ssh
ACCEPT     all  --  anywhere             anywhere             ctstate RELATED,ESTABLISHED

Now that we’ve safeguarded our existing connections and the replies to the connections we initiated, we can deny everything else that wasn’t matched.

csaba ~ # iptables -A INPUT -i eth0 -p tcp -j DROP
csaba ~ # iptables -L
Chain INPUT (policy ACCEPT)
target     prot opt source               destination
ACCEPT     tcp  --  anywhere             anywhere             tcp dpt:ssh
ACCEPT     all  --  anywhere             anywhere             ctstate RELATED,ESTABLISHED
DROP       tcp  --  anywhere             anywhere

We’ve appended another line, with a rule to DROP all connections that match. Remember: this rule will only apply if none of the previous ones actually match.

There are two ways to refuse a connections.

You can use DROP, which is equivalent to dialing a non-existent phone number with the difference that, after some time, the network connection times out. With a phone number, a robot informs you that the number does not exist. But the end result from the point of view of the caller is the same: it thinks that the destination does not exist.
The second way to refuse the connection is with the rule, REJECT, and an optional message. This is analogous to the number you are trying to call being busy. You may know that there is a number, you know it can be called, but it simply refuses to take your calls. Optionally, you can provide a message with a REJECT rule; the default is “ICMP port unreachable” or something similar.

Allow Computers to Access the Internet

At this point, we have some basic rules for the INPUT chain. But we have a network of computers having private IP addresses. We need to provide a gateway to the Internet. This is also done by iptables: the firewall.

Network Address Translation (NAT)

Likely, you’ve already heard this term: NAT. This refers to the procedure of translating one network address to another and forwarding the information between the two. It’s most frequently used in architectures like our own. The gateway has to do NAT in order to translate any computer’s IP from the LAN into its own public IP and then back.

Routing is the procedure by which a system can figure out on what network interfaces and toward what gateway it can communicate to reach its destination. Each computer has a routing table of its own to determine this. Iptables can hook into this routing procedure at two different points: before and after the procedure has occurred.

Nating with Iptables

csaba ~ # iptables -t nat -A POSTROUTING -o eth0 -j SNAT --to-source 89.72.31.243

This command adds a rule as POSTROUTING to the NATing table (-t nat). POSTROUTING essentially means that the packets first pass the routing mechanism on the gateway, and, only after that are they modified. The rule -j SNAT means Source NAT; the source address of the packets will be changed to the address on the interface specified by -o eth0 – in our case, to the IP address specified by the option, --to-source. So, anyone contacted by a computer in your network will assume that it is talking directly to your gateway. It will have absolutely no clue about the fact that the packets are destined for some different computer. The gateway, using iptables, will keep an internal list of all the translated IP addresses, and, when a reply comes, it will revert the change and pass the answer to the computer inside the network.

Allow Client from the Internet to the Email Server

Another problem that we face is what to do when we have a server that is behind a firewall. We need to allow the clients, coming from the Internet, to communicate with our server in some way. This is the case with our mail server. When an email arrives that has to be delivered to a mail account on our server, the sending email server will have to connect to our receiving one.

But our mail server only has a private IP address. There is no way that an external computer could connect to it directly. On the other hand, our gateway has an external IP that anyone could connect to. The solution? Open a port on our gateway so that a request from the Internet to that port will actually go to our email server. The answer, of course, will travel through the gateway back to the client. The trick is to use a different type of NAT here, called Destination NAT. This changes the packets destination and then reverts them back when the response occurs. Think of DNAT as the reverse of SNAT.

Tip: You may know this feature as “Virtual Server,” if you’ve ever played around with small home routers.

csaba ~ # iptables -t nat -A PREROUTING -i eth0 -p tcp --dport 25 -j DNAT --to-destination 192.168.1.2:25

So, what is happening here? A packet comes in to our gateway at the port 25 (the port used for SMTP, the email protocol the whole Internet uses). The rule above catches this packet because of the --dport 25 option, which basically says, “Match anything that goes to this port on the interface specified by -i eth0. Now that the packet is matched, change its destination from the current machine (the gateway) to the one specified by --to-destination.” Please note that you can specify the port explicitly after the IP address by separating it with a colon.

Finally, note that this is in the PREROUTING hook. The destination has to be changed before the routing actually takes place. Otherwise, the packets would end up on the gateway and find no way to the mail server.

Persisting iptables Configuration

The rules you insert or append to iptables are in memory. After a reboot, spoof: everything is gone! To save your configuration, you should dump it into a file, like so:

csaba ~ # iptables-save > /some/directory/my_rules.fw

The file’s name doesn’t matter, nor does its extension. To restore the rules, run this command when your computer starts.

iptables-restor < /some/directory/my_rules.fw

If you take a look at the saved content, you’ll see that they’re the same parameters that we used with the iptables commands. There are some minor differences, but you can easily understand the saved file, and could even write your own such files by hand and load them.

Final Thoughts

In closing, here are some thoughts on when and when not to use a firewall with a Linux computer.

Use a firewall on Linux when you configure a server (like a gateway in our example), or when you have a computer with important information on it that is directly exposed to the Internet. Before you jump on to configure your iptables, consider the potential danger. Ask yourself: is my computer known on the Internet? There are a few billion computers out there. If yours is just one, the chance of being targeted is incredibly low. Are there people directly interested in your information? Hackers don’t waste time stealing random data in the hopes that they might find something. They usually know what they are looking for, and then target the computers containing the desired information. Of course, there are countless attacks against random computers that attempt to install some kind of worm or virus, but on Linux, you are immune by design.

Don’t waste your time with configuring a firewall on Linux when it is a computer that is alway behind a firewall, such as your home PC behind your home router, or when you have no particularly important information on your laptop. If you keep the services that listen on the network to a minimum and have a decently secure password, you can forget your firewall. I personally have no personal computer, laptop or smartphone with a firewall running. I have, however, a home router with a well-configured firewall.

I think you can safely apply these ideas to Mac OSX as well. If you’re a Windows user, sorry: a firewall is your first line of defense. For Linux or MacOSX, though, a firewall is your last line of defense. A carefully selected password and not running useless services should handle the bulk of your computer’s protection.

Thanks for reading. Questions?

Tuts+ Premium Cash Back Offer: 3 Days to Go

Joel Bankhead — Fri, 17 May 2013 17:00:56 +0000

This offer ends soon! Act now and don’t miss out on cash back when trying a monthly Tuts+ Premium subscription.

At $19 a month, Tuts+ Premium is fantastic value. But it’s even better when we hand your first $19 right back to you!

For a limited time, we’re offering $19 cash back to new Tuts+ Premium monthly subscribers when signing up via PayPal. If you’ve been thinking about checking out our extensive library of courses, tutorials, eBooks and guides there’s never been a better time to join up and dive in.

This offer ends at noon on the 20th of May AEST, so act fast.

Become a Tuts+ Premium Member and take your creative & technical skills to a new level.

What can you learn on Tuts+ Premium? Glad you asked! Currently, more than 15,000 members are sharpening their skills in a wide range of areas including web design, web development, Photoshop, vectors, video effects, and many more. With Tuts+ Premium you learn from expert instructors in every field.

Join now and get instant access to your very own library of courses, tutorials, and eBooks, available whenever you need them. Become part of a community of over 15,000 members and start getting better at the skills you care about. Our dedicated team adds new content weekly, so there’s always something fresh to sink your teeth into.

Join Tuts+ Premium

How to Write Testable and Maintainable Code in PHP

Chris Fidao — Wed, 15 May 2013 20:08:11 +0000

Frameworks provide a tool for rapid application development, but often accrue technical debt as rapidly as they allow you to create functionality. Technical debt is created when maintainability isn't a purposeful focus of the developer. Future changes and debugging become costly, due to a lack of unit testing and structure.

Here's how to begin structuring your code to achieve testability and maintainability – and save you time.

We'll Cover (loosely)

DRY
Dependency Injection
Interfaces
Containers
Unit Tests with PHPUnit

Let's begin with some contrived, but typical code. This might be a model class in any given framework.

class User {

public function getCurrentUser()
{
    $user_id = $_SESSION['user_id'];

    $user = App::db->select('id, username')
                    ->where('id', $user_id)
                    ->limit(1)
                    ->get();

    if ( $user->num_results() > 0 )
    {
            return $user->row();
    }

    return false;
}

}

This code will work, but needs improvement:

This isn't testable.
- We're relying on the $_SESSION global variable. Unit-testing frameworks, such as PHPUnit, rely on the command-line, where $_SESSION and many other global variables aren't available.
- We're relying on the database connection. Ideally, actual database connections should be avoided in a unit-test. Testing is about code, not about data.
This code isn't as maintainable as it could be. For instance, if we change the data source, we'll need to change the database code in every instance of App::db used in our application. Also, what about instances where we don't want just the current user's information?

An Attempted Unit Test

Here's an attempt to create a unit test for the above functionality.

class UserModelTest extends PHPUnit_Framework_TestCase {

    public function testGetUser()
    {
        $user = new User();

        $currentUser = $user->getCurrentUser();

        $this->assertEquals(1, $currentUser->id);
    }

}

Let's examine this. First, the test will fail. The $_SESSION variable used in the User object doesn't exist in a unit test, as it runs PHP in the command line.

Second, there's no database connection setup. This means that, in order to make this work, we will need to bootstrap our application in order to get the App object and its db object. We'll also need a working database connection to test against.

To make this unit test work, we would need to:

Setup a config setup for a CLI (PHPUnit) run in our application
Rely on a database connection. Doing this means relying on a data source separate from our unit test. What if our test database doesn't have the data we're expecting? What if our database connection is slow?
Relying on an application being bootstrapped increases the overhead of the tests, slowing the unit tests down dramatically. Ideally, most of our code can be tested independent of the framework being used.

So, let's get down to how we can improve this.

Keep Code DRY

The function retrieving the current user is unnecessary in this simple context. This is a contrived example, but in the spirit of DRY principles, the first optimization I'm choosing to make is to generalize this method.

class User {

    public function getUser($user_id)
    {
        $user = App::db->select('user')
                        ->where('id', $user_id)
                        ->limit(1)
                        ->get();

        if ( $user->num_results() > 0 )
        {
            return $user->row();
        }

        return false;
    }

}

This provides a method we can use across our entire application. We can pass in the current user at the time of the call, rather than passing that functionality off to the model. Code is more modular and maintainable when it doesn't rely on other functionalities (such as the session global variable).

However, this is still not testable and maintainable as it could be. We're still relying on the database connection.

Dependency Injection

Let's help improve the situation by adding some Dependency Injection. Here's what our model might look like, when we pass the database connnection into the class.

class User {

    protected $_db;

    public function __construct($db_connection)
    {
        $this->_db = $db_connection;
    }

    public function getUser($user_id)
    {
        $user = $this->_db->select('user')
                        ->where('id', $user_id)
                        ->limit(1)
                        ->get();

        if ( $user->num_results() > 0 )
        {
            return $user->row();
        }

        return false;
    }

}

Now, the dependencies of our User model are provided for. Our class no longer assumes a certain database connection, nor relies on any global objects.

At this point, our class is basically testable. We can pass in a data-source of our choice (mostly) and a user id, and test the results of that call. We can also switch out separate database connections (assuming that both implement the same methods for retrieving data). Cool.

Let's look at what a unit test might look like for that.

<?php

use Mockery as m;
use Fideloper\User;

class SecondUserTest extends PHPUnit_Framework_TestCase {

    public function testGetCurrentUserMock()
    {
        $db_connection = $this->_mockDb();

        $user = new User( $db_connection );

        $result = $user->getUser( 1 );

        $expected = new StdClass();
        $expected->id = 1;
        $expected->username = 'fideloper';

        $this->assertEquals( $result->id, $expected->id, 'User ID set correctly' );
        $this->assertEquals( $result->username, $expected->username, 'Username set correctly' );
    }

    protected function _mockDb()
    {
        // "Mock" (stub) database row result object
        $returnResult = new StdClass();
        $returnResult->id = 1;
        $returnResult->username = 'fideloper';

        // Mock database result object
        $result = m::mock('DbResult');
        $result->shouldReceive('num_results')->once()->andReturn( 1 );
        $result->shouldReceive('row')->once()->andReturn( $returnResult );

        // Mock database connection object
        $db = m::mock('DbConnection');

        $db->shouldReceive('select')->once()->andReturn( $db );
        $db->shouldReceive('where')->once()->andReturn( $db );
        $db->shouldReceive('limit')->once()->andReturn( $db );
        $db->shouldReceive('get')->once()->andReturn( $result );

        return $db;
    }

}

I've added something new to this unit test: Mockery. Mockery lets you "mock" (fake) PHP objects. In this case, we're mocking the database connection. With our mock, we can skip over testing a database connection and simply test our model.

Want to learn more about Mockery?

In this case, we're mocking a SQL connection. We're telling the mock object to expect to have the select, where, limit and get methods called on it. I am returning the Mock, itself, to mirror how the SQL connection object returns itself ($this), thus making its method calls "chainable". Note that, for the get method, I return the database call result – a stdClass object with the user data populated.

This solves a few problems:

We're testing only our model class. We're not also testing a database connection.
We're able to control the inputs and outputs of the mock database connection, and, therefore, can reliably test against the result of the database call. I know I'll get a user ID of "1" as a result of the mocked database call.
We don't need to bootstrap our application or have any configuration or database present to test.

We can still do much better. Here's where it gets interesting.

Interfaces

To improve this further, we could define and implement an interface. Consider the following code.

interface UserRepositoryInterface {
    public function getUser($user_id);
}

class MysqlUserRepository implements UserRepositoryInterface {

    protected $_db;

    public function __construct($db_conn)
    {
        $this->_db = $db_conn;
    }

    public function getUser($user_id)
    {
        $user = $this->_db->select('user')
                    ->where('id', $user_id)
                    ->limit(1)
                    ->get();

        if ( $user->num_results() > 0 )
        {
            return $user->row();
        }

        return false;
    }

}

class User {

    protected $userStore;

    public function __construct(UserRepositoryInterface $user)
    {
        $this->userStore = $user;
    }

    public function getUser($user_id)
    {
        return $this->userStore->getUser($user_id);
    }

}

There's a few things happening here.

First, we define an interface for our user data source. This defines the addUser() method.
Next, we implement that interface. In this case, we create a MySQL implementation. We accept a database connection object, and use it to grab a user from the database.
Lastly, we enforce the use of a class implementing the UserInterface in our User model. This guarantees that the data source will always have a getUser() method available, no matter which data source is used to implement UserInterface.

Note that our User object type-hints UserInterface in its constructor. This means that a class implementing UserInterface MUST be passed into the User object. This is a guarantee we are relying on – we need the getUser method to always be available.

What is the result of this?

Our code is now fully testable. For the User class, we can easily mock the data source. (Testing the implementations of the datasource would be the job of a separate unit test).
Our code is much more maintainable. We can switch out different data sources without having to change code throughout our application.
We can create ANY data source. ArrayUser, MongoDbUser, CouchDbUser, MemoryUser, etc.
We can easily pass any data source to our User object if we need to. If you decide to ditch SQL, you can just create a different implementation (for instance, MongoDbUser) and pass that into your User model.

We've simplified our unit test, as well!

<?php

use Mockery as m;
use Fideloper\User;

class ThirdUserTest extends PHPUnit_Framework_TestCase {

    public function testGetCurrentUserMock()
    {
        $userRepo = $this->_mockUserRepo();

        $user = new User( $userRepo );

        $result = $user->getUser( 1 );

        $expected = new StdClass();
        $expected->id = 1;
        $expected->username = 'fideloper';

        $this->assertEquals( $result->id, $expected->id, 'User ID set correctly' );
        $this->assertEquals( $result->username, $expected->username, 'Username set correctly' );
    }

    protected function _mockUserRepo()
    {
        // Mock expected result
        $result = new StdClass();
        $result->id = 1;
        $result->username = 'fideloper';

        // Mock any user repository
        $userRepo = m::mock('Fideloper\Third\Repository\UserRepositoryInterface');
        $userRepo->shouldReceive('getUser')->once()->andReturn( $result );

        return $userRepo;
    }

}

We've taken the work of mocking a database connection out completely. Instead, we simply mock the data source, and tell it what to do when getUser is called.

But, we can still do better!

Containers

Consider the usage of our current code:

// In some controller
$user = new User( new MysqlUser( App:db->getConnection("mysql") ) );
$user->id = App::session("user->id");

$currentUser = $user->getUser($user_id);

Our final step will be to introduce containers. In the above code, we need to create and use a bunch of objects just to get our current user. This code might be littered across your application. If you need to switch from MySQL to MongoDB, you'll still need to edit every place where the above code appears. That's hardly DRY. Containers can fix this.

A container simply "contains" an object or functionality. It's similar to a registry in your application. We can use a container to automatically instantiate a new User object with all needed dependencies. Below, I use Pimple, a popular container class.

// Somewhere in a configuration file
$container = new Pimple();
$container["user"] = function() {
    return new User( new MysqlUser( App:db->getConnection('mysql') ) );
}

// Now, in all of our controllers, we can simply write:
$currentUser = $container['user']->getUser( App::session('user_id') );

I've moved the creation of the User model into one location in the application configuration. As a result:

We've kept our code DRY. The User object and the data store of choice is defined in one location in our application.
We can switch out our User model from using MySQL to any other data source in ONE location. This is vastly more maintainable.

Final Thoughts

Over the course of this tutorial, we accomplished the following:

Kept our code DRY and reusable
Created maintainable code – We can switch out data sources for our objects in one location for the entire application if needed
Made our code testable – We can mock objects easily without relying on bootstrapping our application or creating a test database
Learned about using Dependency Injection and Interfaces, in order to enable creating testable and maintainable code
Saw how containers can aid in making our application more maintainable

I'm sure you've noticed that we've added much more code in the name of maintainability and testability. A strong argument can be made against this implementation: we're increasing complexity. Indeed, this requires a deeper knowledge of code, both for the main author and for collaborators of a project.

However, the cost of explanation and understanding is far out-weighed by the extra overall decrease in technical debt.

The code is vastly more maintainable, making changes possible in one location, rather than several.
Being able to unit test (quickly) will reduce bugs in code by a large margin – especially in long-term or community-driven (open-source) projects.
Doing the extra-work up front will save time and headache later.

Resources

You may include Mockery and PHPUnit into your application easily using Composer. Add these to your "require-dev" section in your composer.json file:

"require-dev": {
    "mockery/mockery": "0.8.*",
    "phpunit/phpunit": "3.7.*"
}

You can then install your Composer-based dependencies with the "dev" requirements:

$ php composer.phar install --dev

Learn more about Mockery, Composer and PHPUnit here on Nettuts+.

For PHP, consider using Laravel 4, as it makes exceptional use of containers and other concepts written about here.

Thanks for reading!

Real Time Chat With NodeJS, Socket.io and ExpressJS

Krasimir Tsonev — Tue, 14 May 2013 17:57:14 +0000

NodeJS gives me the ability to write back-end code in one of my favorite languages: JavaScript. It's the perfect technology for building real time applications. In this tutorial, I'll show you how to build a web chat application, using ExpressJS and Socket.io.

Setup Environment

Of course, the first thing to do is get NodeJS installed on your system. If you are a Windows or Mac user, you can visit nodejs.org and download the installer. If you instead prefer Linux, I'd suggest that you refer to this link. Although I won’t go into further details on this, if you encounter any installation issues, I’m happy to help; just leave a comment below this post.

Once you have NodeJS installed, you’re ready to setup the needed instruments.

ExpressJS – this will manage the server and the response to the user
Jade – template engine
Socket.io – allows for real time communication between the front-end and back-end

Continuing on, within an empty directory, create a package.json file with the following content.

{
    "name": "RealTimeWebChat",
    "version": "0.0.0",
    "description": "Real time web chat",
    "dependencies": {
        "socket.io": "latest",
        "express": "latest",
        "jade": "latest"
    },
    "author": "developer"
}

By using the console (under Windows – command prompt), navigate to your folder and execute:

npm install

Within a few seconds, you’ll have all the necessary dependencies downloaded to the node_modules directory.

Developing the Backend

Let’s begin with a simple server, which will deliver the application's HTML page, and then continue with the more interesting bits: the real time communication. Create an index.js file with the following core expressjs code:

var express = require("express");
var app = express();
var port = 3700;

app.get("/", function(req, res){
    res.send("It works!");
});

app.listen(port);
console.log("Listening on port " + port);

Above, we’ve created an application and defined its port. Next, we registered a route, which, in this case, is a simple GET request without any parameters. For now, the route’s handler simply sends some text to the client. Finally, of course, at the bottom, we run the server. To initialize the application, from the console, execute:

node index.js

The server is running, so you should be able to open http://127.0.0.1:3700/ and see:

It works!

Now, instead of "It works" we should serve HTML. Instead of pure HTML, it can be beneficial to use a template engine. Jade is an excellent choice, which has good integration with ExpressJS. This is what I typically use in my own projects. Create a directory, called tpl, and put the following page.jade file within it:

!!!
html
    head
        title= "Real time web chat"
    body
        #content(style='width: 500px; height: 300px; margin: 0 0 20px 0; border: solid 1px #999; overflow-y: scroll;')
        .controls
            input.field(style='width:350px;')
            input.send(type='button', value='send')

The Jade's syntax is not so complex, but, for a full guide, I suggest that you refer to jade-lang.com. In order to use Jade with ExpressJS, we require the following settings.

app.set('views', __dirname + '/tpl');
app.set('view engine', "jade");
app.engine('jade', require('jade').__express);
app.get("/", function(req, res){
    res.render("page");
});

This code informs Express where your template files are, and which template engine to use. It all specifies the function that will process the template's code. Once everything is setup, we can use the .render method of the response object, and simply send our Jade code to the user.

The output isn’t special at this point; nothing more than a div element (the one with id content), which will be used as a holder for the chat messages and two controls (input field and button), which we will use to send the message.

Because we will use an external JavaScript file that will hold the front-end logic, we need to inform ExpressJS where to look for such resources. Create an empty directory, public, and add the following line before the call to the .listen method.

app.use(express.static(__dirname + '/public'));

So far so good; we have a server that successfully responds to GET requests. Now, it’s time to add Socket.io integration. Change this line:

app.listen(port);

to:

var io = require('socket.io').listen(app.listen(port));

Above, we passed the ExpressJS server to Socket.io. In effect, our real time communication will still happen on the same port.

Moving forward, we need to write the code that will receive a message from the client, and send it to all the others. Every Socket.io application begins with a connection handler. We should have one:

io.sockets.on('connection', function (socket) {
    socket.emit('message', { message: 'welcome to the chat' });
    socket.on('send', function (data) {
        io.sockets.emit('message', data);
    });
});

The object, socket, which is passed to your handler, is actually the socket of the client. Think about it as a junction between your server and the user's browser. Upon a successful connection, we send a welcome type of message, and, of course, bind another handler that will be used as a receiver. As a result, the client should emit a message with the name, send, which we will catch. Following that, we simply forward the data sent by the user to all other sockets with io.sockets.emit.

With the code above, our back-end is ready to receive and send messages to the clients. Let's add some front-end code.

Developing the Front-end

Create chat.js, and place it within the public directory of your application. Paste the following code:

window.onload = function() {

    var messages = [];
    var socket = io.connect('http://localhost:3700');
    var field = document.getElementById("field");
    var sendButton = document.getElementById("send");
    var content = document.getElementById("content");

    socket.on('message', function (data) {
        if(data.message) {
            messages.push(data.message);
            var html = '';
            for(var i=0; i<messages.length; i++) {
                html += messages[i] + '<br />';
            }
            content.innerHTML = html;
        } else {
            console.log("There is a problem:", data);
        }
    });

    sendButton.onclick = function() {
        var text = field.value;
        socket.emit('send', { message: text });
    };

}

Our logic is wrapped in a .onload handler just to ensure that all the markup and external JavaScript is fully loaded. In the next few lines, we create an array, which will store all the messages, a socket object, and few shortcuts to our DOM elements. Again, similar to the back-end, we bind a function, which will react to the socket's activity. In our case, this is an event, named message. When such an event occurs, we expect to receive an object, data, with the property, message. Add that message to our storage and update the content div. We’ve also included the logic for sending the message. It’s quite simple, simply emitting a message with the name, send.

If you open http://localhost:3700, you will encounter some errors popup. That's because we need to update page.jade to contain the necessary JavaScript files.

head
    title= "Real time web chat"
    script(src='/chat.js')
    script(src='/socket.io/socket.io.js')

Notice that Socket.io manages the delivery of socket.io.js. You don't have to worry about manually downloading this file.

We can again run our server with node index.js in the console and open http://localhost:3700. You should see the welcome message. Of course, if you send something, it should be shown in the content's div. If you want to be sure that it works, open a new tab (or, better, a new browser) and load the application. The great thing about Socket.io is that it works even if you stop the NodeJS server. The front-end will continue to work. Once the server is booted up again, your chat will be fine too.

In its current state, our chat is not perfect, and requires some improvements.

Improvements

The first change that we need to make is to the identity of the messages. Currently, it's not clear which messages is sent by whom. The good thing is that we don't have to update our NodeJS code to achieve this. That's because the server simply forwards the data object. So, we need to add a new property there, and read it later. Before making corrections to chat.js, let’s add a new input field, where the user may add his/her name. Within page.jade, change the controls div:

.controls
    | Name: 
    input#name(style='width:350px;')
    br
    input#field(style='width:350px;')
    input#send(type='button', value='send')

Next, in code.js:

window.onload = function() {

    var messages = [];
    var socket = io.connect('http://localhost:3700');
    var field = document.getElementById("field");
    var sendButton = document.getElementById("send");
    var content = document.getElementById("content");
    var name = document.getElementById("name");

    socket.on('message', function (data) {
        if(data.message) {
            messages.push(data);
            var html = '';
            for(var i=0; i<messages.length; i++) {
                html += '<b>' + (messages[i].username ? messages[i].username : 'Server') + ': </b>';
                html += messages[i].message + '<br />';
            }
            content.innerHTML = html;
        } else {
            console.log("There is a problem:", data);
        }
    });

    sendButton.onclick = function() {
        if(name.value == "") {
            alert("Please type your name!");
        } else {
            var text = field.value;
            socket.emit('send', { message: text, username: name.value });
        }
    };

}

To summarize the changes, we’ve:

Added a new shortcut for the username's input field
Updated the presentation of the messages a bit
Appended a new username property to the object, which is sent to the server

If the the number of messages becomes too high, the user will need to scroll the div:

content.innerHTML = html;
content.scrollTop = content.scrollHeight;

Keep in mind that the above solution will likely not work in IE7 and below, but that’s okay: it’s time for IE7 to fade away. However, if you want to ensure support, feel free to use jQuery:

$("#content").scrollTop($("#content")[0].scrollHeight);

It would also be nice if the input field is cleared after sending the message:

socket.emit('send', { message: text, username: name.value });
field.value = "";

The final boring problem is the clicking of the send button each time. With a touch of jQuery, we can listen for when the user presses the Enter key.

$(document).ready(function() {
    $("#field").keyup(function(e) {
        if(e.keyCode == 13) {
            sendMessage();
        }
    });
});

The function, sendMessage, could be registered, like so:

sendButton.onclick = sendMessage = function() {
    ...
};

Please note that this isn’t a best practice, as it is registered as a global function. But, for our little test here, it’ll be fine.

Conclusion

NodeJS is an extremely useful technology, and provides us with a great deal of power and joy, especially when considering the fact that we can write pure JavaScript. As you can see, with only a few lines of code, we managed to write a fully functional real time chat application. Pretty neat!

Want to learn more about building web apps with ExpressJS? We’ve got you covered!

Mass Assignment, Rails, and You

Arun Srinivasan — Mon, 13 May 2013 18:00:20 +0000

Early in 2012, a developer, named Egor Homakov, took advantage of a security hole at Github (a Rails app) to gain commit access to the Rails project.

His intent was mostly to point out a common security issue with many Rails apps that results from a feature, known as mass assignment (and did so rather loudly). In this article, we'll review what mass assignment is, how it can be a problem, and what you can do about it in your own applications.

What is Mass Assignment?

To begin, let's first take a look at what mass assignment means, and why it exists. By way of an example, imagine that we have the following User class in our application:

# Assume the following fields: [:id, :first, :last, :email]
class User < ActiveRecord::Base
end

Mass assignment allows us to set a bunch of attributes at once:

attrs = {:first => "John", :last => "Doe", :email => "john.doe@example.com"}
user = User.new(attrs)
user.first #=> "John"
user.last  #=> "Doe"
user.email #=> "john.doe@example.com"

Without the convenience of mass assignment, we'd have to write an assignment statement for each attribute to achieve the same result. Here’s an example:

attrs = {:first => "John", :last => "Doe", :email => "john.doe@example.com"}
user = User.new
user.first = attrs[:first]
user.last  = attrs[:last]
user.email = attrs[:email]
user.first #=> "John"
user.last  #=> "Doe"
user.email #=> "john.doe@example.com"

Obviously, this can get tedious and painful; so we bow at the feet of laziness and say, yes yes, mass assignment is a good thing.

The (Potential) Problem With Mass Assignment

One problem with sharp tools is that you can cut yourself with them.

But wait! One problem with sharp tools is that you can cut yourself with them. Mass assignment is no exception to this rule.

Suppose now that our little imaginary application has acquired the ability to fire missiles. As we don't want the world to turn to ash, we add a boolean permission field to the User model to decide who can fire missiles.

class AddCanFireMissilesFlagToUsers < ActiveRecord::Migration
  def change
    add_column :users, :can_fire_missiles, :boolean, :default => false
  end
end

Let's also assume that we have a way for users to edit their contact information: this might be a form somewhere that is accessible to the user with text fields for the user's first name, last name, and email address.

Our friend John Doe decides to change his name and update his email account. When he submits the form, the browser will issue a request similar to the following:

PUT http://missileapp.com/users/42?user[first]=NewJohn&user[email]=john.doe@newemail.com

The update action within the UsersController might look something like:

def update
  user = User.find(params[:id])
  if user.update_attributes(params[:user]) # Mass assignment!
    redirect_to home_path
  else
    render :edit
  end
end

Given our example request, the params hash will look similar to:

{:id => 42, :user => {:first => "NewJohn", :email => "john.doe@newemail.com"}
# :id - parsed by the router
# :user - parsed from the incoming querystring

Now let's say that NewJohn gets a little sneaky. You don't necessarily need a browser to issue an HTTP request, so he writes a script that issues the following request:

PUT http://missileapp.com/users/42?user[can_fire_missiles]=true

Fields, like :admin, :owner, and :public_key, are quite easily guessable.

When this request hits our update action, the update_attributes call will see {:can_fire_missiles => true}, and give NewJohn the ability to fire missiles! Woe has become us.

This is exactly how Egor Homakov gave himself commit access to the Rails project. Because Rails is so convention-heavy, fields like :admin, :owner, and :public_key are quite easily guessable. Further, if there aren't protections in place, you can gain access to things that you're not supposed to be able to touch.

How to Deal With Mass Assignment

So how do we protect ourselves from wanton mass assignment? How do we prevent the NewJohns of the world from firing our missiles with reckless abandon?

Luckily, Rails provides a couple tools to manage the issue: attr_protected and attr_accessible.

`attr_protected`: The BlackList

Using attr_protected, you can specify which fields may never be mass-ly assignable:

class User < ActiveRecord::Base
  attr_protected :can_fire_missiles
end

Now, any attempt to mass-assign the can_fire_missiles attribute will fail.

`attr_accessible`: The WhiteList

The problem with attr_protected is that it's too easy to forget to add a newly implemented field to the list.

This is where attr_accessible comes in. As you might have guessed, it's the opposite of attr_protected: only list the attributes that you want to be mass-assignable.

As such, we can switch our User class to this approach:

class User < ActiveRecord::Base
  attr_accessible :first, :last, :email
end

Here, we're explicitly listing out what can be mass-assigned. Everything else will be disallowed. The advantage here is that if we, say, add an admin flag to the User model, it will automatically be safe from mass-assignment.

As a general rule, you should prefer attr_accessible to attr_protected, as it helps you err on the side of caution.

Mass Assignment Roles

Rails 3.1 introduced the concept of mass-assignment "roles". The idea is that you can specify different attr_protected and attr_accessible lists for different situations.

class User < ActiveRecord::Base
  attr_accessible :first, :last, :email             # :default role
  attr_accessible :can_fire_missiles, :as => :admin # :admin role
end

user = User.new({:can_fire_missiles => true}) # uses the :default role  
user.can_fire_missiles #=> false  

user2 = User.new({:can_fire_missiles => true}, :as => :admin)  
user.can_fire_missiles #=> true

Application-wide Configuration

You can control mass assignment behavior in your application by editing the config.active_record.whitelist_attributes setting within the config/application.rb file.

If set to false, mass assignment protection will only be activated for the models where you specify an attr_protected or attr_accessible list.

If set to true, mass assignment will be impossible for all models unless they specify an attr_protected or attr_accessible list. Please note that this option is enabled by default from Rails 3.2.3 forward.

Strictness

Beginning with Rails 3.2, there is additionally a configuration option to control the strictness of mass assignment protection: config.active_record.mass_assignment_sanitizer.

If set to :strict, it will raise an ActiveModel::MassAssignmentSecurity::Error any time that your application attempts to mass-assign something it shouldn't. You'll need to handle these errors explicitly. As of v3.2, this option is set for you in the development and test environments (but not production), presumably to help you track down where mass-assignment issues might be.

If not set, it will handle mass-assignment protection silently - meaning that it will only set the attributes it's supposed to, but won't raise an error.

Rails 4 Strong Parameters: A Different Approach

Mass assignment security is really about handling untrusted input.

The Homakov Incident initiated a conversation around mass assignment protection in the Rails community (and onward to other languages, as well); an interesting question was raised: does mass assignment security belong in the model layer?

Some applications have complex authorization requirements. Trying to handle all special cases in the model layer can begin to feel clunky and over-complicated, especially if you find yourself plastering roles all over the place.

A key insight here is that mass assignment security is really about handling untrusted input. As a Rails application receives user input in the controller layer, developers began wondering whether it might be better to deal with the issue there instead of ActiveRecord models.

The result of this discussion is the Strong Parameters gem, available for use with Rails 3, and a default in the upcoming Rails 4 release.

Assuming that our missile application is bult on Rails 3, here's how we might update it for use with the stong parameters gem:

Add the gem

Add the following line to the Gemfile:

gem strong_parameters

Turn off model-based mass assignment protection

Within config/application.rb:

config.active_record.whitelist_attributes = false

Tell the models about it

class User < ActiveRecord::Base
  include ActiveModel::ForbiddenAttributesProtection
end

Update the controllers

class UsersController < ApplicationController
  def update
    user = User.find(params[:id])
    if user.update_attributes(user_params) # see below
      redirect_to home_path
    else
      render :edit
    end
  end

  private

  # Require that :user be a key in the params Hash,
  # and only accept :first, :last, and :email attributes
  def user_params
    params.require(:user).permit(:first, :last, :email)
  end
end

Now, if you attempt something like user.update_attributes(params), you'll get an error in your application. You must first call permit on the params hash with the keys that are allowed for a specific action.

The advantage to this approach is that you must be explicit about which input you accept at the point that you're dealing with the input.

Note: If this was a Rails 4 app, the controller code is all we'd need; the strong parameters functionality will be baked in by default. As a result, you won't need the include in the model or the separate gem in the Gemfile.

Wrapping Up

Mass assignment can be an incredibly useful feature when writing Rails code. In fact, it's nearly impossible to write reasonable Rails code without it. Unfortunately, mindless mass assignment is also fraught with peril.

Hopefully, you're now equipped with the necessary tools to navigate safely in the mass assignment waters. Here's to fewer missiles!